@joewinke/jatui 0.38.2 → 0.38.4

package/CLAUDE.md

@@ -69,7 +69,7 @@ Then import:
 | `Empty` | Zero-state surface — v1 thin copy/children block still works; pass `title` for the v2 hero layout (upstreamed from the IDE's EmptyState): named `glyph` (11 curated Heroicons), `size` (sm/md/lg), `pulse` (reduced-motion gated, tinted with `--color-primary`), `icon` snippet override, CTA `actions` snippet, `description`, extra `children` below. | `title` (opts into v2), `description`, `glyph`, `size`, `pulse`, `icon`/`actions` (snippets), `copy`, `class`, `children` |
 | `ErrorState` | Standard "this failed" surface (upstreamed from the IDE's ErrorState) — error-token themed icon, optional Retry button, extra `actions`, collapsible `details` block for raw error output. Centered card mirroring `Empty` v2. | `title`, `message`, `details`, `retryLabel`, `onRetry`, `size`, `actions` (snippet) |
 | `HunkDiffView` | Side-by-side diff with line numbers, red/green backgrounds, strikethrough on removed lines, inline word-level highlights via the `diff` lib. Used for reviewing YAML/text changes per hunk. | `oldText: string \| null`, `newText: string \| null`, `unified?: boolean` |
-| `JumpToLatest` | "Jump to latest" pill for streaming transcripts (pairs with `createStickToBottom`) — shows when the reader has scrolled away from the live edge, badges the unread arrival count, jumps + resumes following on click. Position inside a `relative` wrapper that also holds the scroll element. | `visible`, `unreadCount`, `label`, `onclick` |
+| `JumpToLatest` | "Jump to latest" pill for streaming transcripts (pairs with `createStickToBottom`) — shows when the reader has scrolled away from the live edge, badges the unread arrival count, jumps + resumes following on click. Position inside a `relative` wrapper that also holds the scroll element. | `visible`, `unreadCount`, `label`, `text?` (visible words beside the arrow), `onclick` |
 | `ContextMenu` | Floating right-click (or programmatic) action menu, positioned via `use:floating` at a cursor point. Real `<button>`s, per-item `icon`/`variant`/`disabled`, dividers, click-outside + Escape dismiss, arrow-key/Home/End roving nav (focus starts on the first item). Items may declare `submit: SubmitConfig` to POST to a SvelteKit form action instead of (or in addition to) `onSelect` — a hidden `<form>` is built, requestSubmit()ed, then removed, so `use:enhance` fires exactly like a regular form submission. **Items also support nested `submenu: ContextMenuItem[]`** (right-side popover on hover/focus/ArrowRight, chevron indicator, ArrowLeft/Escape closes just the submenu — submenus open on parent-item focus **without stealing focus into the submenu**; ArrowRight is the explicit "enter the submenu" gesture) **and inline `content: Snippet`** (replaces the default icon+label row with an arbitrary widget — the wrapping button still closes the menu, so widgets that shouldn't must `event.stopPropagation()`). `autoFocus` (default true) can be set false to suppress auto-focus of the first item on open. | `open` (bindable), `x`, `y`, `items: ContextMenuItem[]`, `header?`, `zIndex?`, `autoFocus?`, `onClose?` |
 | `ContextMenuTrigger` | Wraps content with the standard right-click + "⋯" touch affordance, backed by `ContextMenu`. Use instead of hand-rolling `oncontextmenu` + a kebab button per row/card. | `items: ContextMenuItem[]`, `children` (snippet), `header?`, `triggerLabel?`, `hideButton?`, `zIndex?`, `class?` |
 | `Tooltip` | Component-shaped wrapper around the shared `use:tooltip` action — for cases where you can't easily add an attribute to the target element (wrap a chip / badge / icon in the tooltip instead). Warm/cool window + `aria-describedby` are shared with the action. Prefer `use:tooltip` directly when you own the element. | `content: string`, `placement?`, `delayMs?`, `disabled?`, `display?`, `children` (snippet) |
@@ -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, `Shift+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, t theater, ? 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; only a gesture that actually moves the PANE pauses it — a wheel that scrolls the page doesn't — behind a "Resume following" pill, and it resumes by itself on seek / line or chapter click / play after pause / `followResumeMs` (6000) idle while playing; a hovered chapter fills its whole span in the theme accent with full-height edges), `followResumeMs?`, `theater?` (bindable — theater mode, NOT fullscreen: control-bar button + `t`, the HOST lays the page out full-width; a side transcript moves below; remembered per viewer as the `player.theater` setting via `settingsStore`, else guarded localStorage), `theaterButton?` (true), `onTheaterChange?`, `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,13 @@
 	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,
+		FOLLOW_RESUME_IDLE_MS,
+		type ReaderScrollWatch
+	} from '../video/transcriptFollow';
+	import JumpToLatest from './basic/JumpToLatest.svelte';
 	import type {
 		VideoBookmark,
 		VideoChapter,
@@ -239,8 +246,11 @@
 	import type { ResumePoint } from '../video/advisors/resume-point';
 	import { idleDetectionSupported } from '../video/presence';
 	import {
+		coerce,
 		createSettingsSession,
+		localSettingsStore,
 		panelGroups,
+		settingSpec,
 		VIDEO_SETTINGS,
 		type SettingAvailability,
 		type SettingsSession,
@@ -272,7 +282,11 @@
 		talkTime = [],
 		startAt = null,
 		transcriptPosition = 'below',
-		transcriptMaxHeight = '18rem',
+		transcriptMaxHeight,
+		followResumeMs = FOLLOW_RESUME_IDLE_MS,
+		theater = $bindable(false),
+		theaterButton = true,
+		onTheaterChange,
 		/**
 		 * CORS mode for the <video> element — passed straight through as the
 		 * `crossorigin` attribute. `'anonymous'` asks the server for a
@@ -431,7 +445,35 @@
 		/** 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;
+		/**
+		 * A reader who scrolled the transcript pane pauses its follow; after
+		 * this long with the pane left alone while playing, follow resumes by
+		 * itself (ms, default 6000; 0 ⇒ only a seek, a line/chapter click,
+		 * play after pause or the "Resume following" pill bring it back).
+		 */
+		followResumeMs?: number;
+		/**
+		 * Theater mode (jatui-ee2ty) — bindable. NOT fullscreen: the player
+		 * only says it wants the page's width; the HOST lays its page out
+		 * full-width (`bind:theater` or `onTheaterChange`). The player itself
+		 * marks its root `vp-theater` / `data-theater` and puts a side
+		 * transcript below the video. The control-bar button and `t` toggle
+		 * it; the choice is remembered per viewer under the `player.theater`
+		 * setting — through `settingsStore` when one is given, else this
+		 * browser's localStorage (every access guarded). The prop is the
+		 * host's default; a remembered choice wins.
+		 */
+		theater?: boolean;
+		/** Show the theater button + `t` key (video only; default true). */
+		theaterButton?: boolean;
+		/** The viewer toggled theater mode (button, `t`, settings panel). */
+		onTheaterChange?: (theater: boolean) => void;
 		crossorigin?: 'anonymous' | 'use-credentials' | null;
 		syncUrlTime?: boolean;
 		/**
@@ -799,6 +841,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 +894,23 @@
 	});
 
 	let transcriptEl: HTMLDivElement | null = null;
+	/** The reader scrolled the pane themselves — auto-follow waits (see transcriptFollow.ts). */
+	let followPaused = $state(false);
+	/** When the reader last scrolled the pane (performance.now()), for the idle resume. */
+	let lastReaderScrollAt = 0;
+	let readerWatch: ReaderScrollWatch | null = null;
+	/** The player scrolls the pane itself: fence it off from reader intent. */
+	function paneScrollTop(pane: HTMLElement, top: number) {
+		readerWatch?.programmatic();
+		pane.scrollTop = top;
+	}
+	function scrollPaneTo(pane: HTMLElement, row: HTMLElement) {
+		readerWatch?.programmatic();
+		return scrollRowIntoPane(pane, row, !reduceMotion);
+	}
+	/** 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);
@@ -874,7 +937,7 @@
 		transPadTop = 0;
 		pendingAutoScrollId = null;
 		vpScrollTop = 0;
-		if (transcriptEl) transcriptEl.scrollTop = 0;
+		if (transcriptEl) paneScrollTop(transcriptEl, 0);
 	}
 
 	/** Append-only growth: heights measured for the prefix stay valid, so only
@@ -1021,7 +1084,7 @@
 		const after = ensureOffsets();
 		const delta = (after[anchor] ?? beforeTop) - beforeTop;
 		if (el && delta !== 0 && st >= beforeTop) {
-			el.scrollTop = st + delta; // fires onscroll → vpScrollTop follows
+			paneScrollTop(el, st + delta); // fires onscroll → vpScrollTop follows
 		}
 	}
 
@@ -1041,9 +1104,16 @@
 			scheduleRowMeasure();
 		});
 		ro.observe(el);
+		const watch = watchReaderScroll(el, () => {
+			lastReaderScrollAt = performance.now();
+			if (activeSegment) followPaused = true;
+		});
+		readerWatch = watch;
 		return {
 			destroy() {
 				ro.disconnect();
+				watch();
+				if (readerWatch === watch) readerWatch = null;
 				transcriptEl = null;
 			}
 		};
@@ -1092,10 +1162,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 +1237,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,13 +1271,14 @@
 			soloKey,
 			mutedKeys,
 			window: bandWindow,
-			hoverChapter,
+			hoverChapter: litChapter,
 			luma: lumaSeries,
 			comments: socialMarkers.comments,
 			likes: socialMarkers.likes,
 			cache: layerCache,
 			colors: {
 				accent: getDaisyUIColor('primary'),
+				chapter: getDaisyUIColor('accent') || getDaisyUIColor('primary'),
 				neutral: getDaisyUIColor('base-content'),
 				marker: getDaisyUIColor('warning'),
 				ribbon: getDaisyUIColor('warning'),
@@ -1261,6 +1346,7 @@
 			if (row.when === 'comments') return socialMarkers.comments.length > 0;
 			if (row.when === 'night') return nightPresent;
 			if (row.when === 'settings') return settingsPanel;
+			if (row.when === 'theater') return theaterAvailable;
 			return true;
 		})
 	);
@@ -1313,6 +1399,7 @@
 		const t = Math.max(0, d > 0 ? Math.min(sec, d) : sec);
 		currentTime = t; // bind:currentTime pushes this to the element
 		if (videoEl) videoEl.currentTime = t;
+		resumeFollow();
 	}
 
 	// ── Speed + rate composer (video/rate/*, mos-5lzns.32) ──────────────────
@@ -2137,6 +2224,14 @@
 			if (night !== undefined) nightDepth = v as number;
 			return;
 		}
+		if (id === 'player.theater') {
+			if (!settingsStore) localTheaterStore.set(id, v);
+			if (theater !== v) {
+				theater = v as boolean;
+				onTheaterChange?.(theater);
+			}
+			return;
+		}
 		userSettings[id] = v;
 	}
 
@@ -2159,6 +2254,30 @@
 		};
 	});
 
+	// ── Theater mode (jatui-ee2ty) ──────────────────────────────────────────
+	// Not fullscreen: the host lays its page out full-width off `theater`.
+	// Remembered per viewer as the `player.theater` setting — the host's
+	// settingsStore when given (the session above reads and writes it), else
+	// this browser's localStorage, read once here.
+	const localTheaterStore = localSettingsStore();
+	const theaterAvailable = $derived(!isAudio && theaterButton);
+	const theaterOn = $derived(theaterAvailable && theater);
+	$effect(() => {
+		if (!theaterAvailable || settingsStore) return;
+		untrack(() => {
+			const spec = settingSpec('player.theater');
+			const stored = spec ? coerce(spec, localTheaterStore.get('player.theater')) : undefined;
+			if (stored !== undefined && stored !== theater) applySetting('player.theater', stored);
+		});
+	});
+	function toggleTheater() {
+		if (!theaterAvailable) return;
+		const next = !theaterOn;
+		if (settingsSession) settingsSession.change('player.theater', next);
+		else applySetting('player.theater', next);
+		flashOsd(next ? 'Theater mode' : 'Default view');
+	}
+
 	/** A viewer choice from outside the panel (N, the moon wheel) — saved like a panel change. */
 	function rememberSetting(id: string, v: SettingValue) {
 		settingsSession?.change(id, v);
@@ -2178,7 +2297,8 @@
 		windDown: windDownProp !== undefined,
 		idle: windDownProp !== undefined && idleDetectionSupported(),
 		resume: resumeKey != null,
-		open: openFrom !== undefined
+		open: openFrom !== undefined,
+		theater: theaterAvailable
 	});
 	const settingsGroups = $derived(settingsOpen ? panelGroups(settingsAvailable) : []);
 	/** What the player is doing right now, per id — the panel shows exactly this. */
@@ -2202,7 +2322,8 @@
 			idleDetection,
 			resumeSnap,
 			openMotion,
-			oneAxis
+			oneAxis,
+			theater: theaterOn
 		};
 		const out: Record<string, SettingValue> = {};
 		for (const spec of VIDEO_SETTINGS) {
@@ -2804,6 +2925,12 @@
 				}
 				return;
 			case 't':
+				// t = theater (YouTube's key); Shift+T = transcript (jatui-ee2ty).
+				if (theaterAvailable) {
+					e.preventDefault();
+					toggleTheater();
+				}
+				return;
 			case 'T':
 				if (sortedSegments.length > 0) {
 					e.preventDefault();
@@ -2884,28 +3011,87 @@
 	});
 
 	// 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) {
+			scrollPaneTo(pane, node);
+			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.
+		paneScrollTop(pane, 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);
+	}
+
+	/**
+	 * Choosing where to be — a seek, a chapter, a line, play after pause —
+	 * is asking for the transcript back (jatui-ee2ty). The follow effect
+	 * lands the new active line; if it didn't change, land it here.
+	 */
+	function resumeFollow() {
+		if (!followPaused) return;
+		followPaused = false;
+		const seg = activeSegment;
+		if (seg) queueMicrotask(() => !followPaused && activeSegment === seg && followSegment(seg));
+	}
+
+	// Idle resume: a reader who scrolled away and then left the pane alone for
+	// `followResumeMs` while it plays gets the follow back by itself.
+	$effect(() => {
+		const ms = followResumeMs;
+		if (!followPaused || paused || !(ms > 0)) return;
+		const tick = () => {
+			if (performance.now() - lastReaderScrollAt >= ms) untrack(resumeFollow);
+		};
+		const id = setInterval(tick, Math.min(1000, Math.max(100, ms / 4)));
+		return () => clearInterval(id);
+	});
+
+	/** Clicking a line is choosing where to be: seek there and follow again. */
+	function onRowClick(seg: VideoTranscriptSegment) {
+		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 +3101,7 @@
 			const node = rowRefs[id];
 			if (!node) return;
 			pendingAutoScrollId = null;
-			node.scrollIntoView({ block: 'nearest', behavior: 'smooth' });
+			if (transcriptEl && !followPaused) scrollPaneTo(transcriptEl, node);
 		});
 	});
 
@@ -2943,7 +3129,9 @@
 <div
 	class="vp-root {className}"
 	bind:this={rootEl}
-	class:vp-side={transcriptPosition === 'side' && sortedSegments.length > 0 && transcriptVisible}
+	class:vp-side={transcriptPosition === 'side' && !theaterOn && sortedSegments.length > 0 && transcriptVisible}
+	class:vp-theater={theaterOn}
+	data-theater={theaterAvailable ? String(theaterOn) : undefined}
 	class:vp-rail-side={railOn}
 	class:vp-one-axis={nativeBarHidden}
 	class:vp-band-transport={bandTransport}
@@ -2961,7 +3149,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}
@@ -3011,6 +3199,7 @@
 					if (nightPresent || guardPresent) nightTick();
 				}}
 				onplay={() => {
+					resumeFollow();
 					if (nightPresent || guardPresent) nightTick();
 					if (windPhase === 'paused') windCancel();
 					if (windOn) windProbe();
@@ -3118,6 +3307,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. -->
@@ -3213,6 +3404,23 @@
 						</svg>
 					</button>
 				{/if}
+				{#if theaterAvailable}
+					<!-- Theater (jatui-ee2ty): asks the host for the page's width —
+					     not fullscreen. Lit while on, like the moon. -->
+					<button
+						type="button"
+						class="vp-theater-btn"
+						class:active={theaterOn}
+						aria-label="Theater mode"
+						aria-pressed={theaterOn}
+						title="{theaterOn ? 'Default view' : 'Theater mode'} · t"
+						onclick={toggleTheater}
+					>
+						<svg viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linejoin="round" aria-hidden="true">
+							<rect x="2.5" y="7" width="19" height="10" rx="1.5" />
+						</svg>
+					</button>
+				{/if}
 				{#if settingsPanel}
 					<button
 						type="button"
@@ -3441,6 +3649,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 +3697,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 +3726,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 +3749,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 +3762,13 @@
 				{/each}
 			{/if}
 		</div>
+		<JumpToLatest
+			visible={followPaused && activeSegment != null}
+			label="Resume following"
+			text="Resume following"
+			onclick={jumpToCurrent}
+		/>
+		</div>
 	{/if}
 
 	{#if keysOpen}
@@ -3614,6 +3841,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 +4079,7 @@
 			grid-area: below;
 		}
 
-		.vp-root.vp-rail-side > .vp-transcript {
+		.vp-root.vp-rail-side > .vp-transcript-wrap {
 			grid-area: transcript;
 		}
 
@@ -4409,8 +4641,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;
@@ -4728,7 +4973,8 @@
 		gap: var(--jatui-space-base, 8px);
 	}
 
-	.vp-night-btn {
+	.vp-night-btn,
+	.vp-theater-btn {
 		display: inline-flex;
 		align-items: center;
 		justify-content: center;
@@ -4741,11 +4987,13 @@
 		transition: color var(--motion-move, 300ms) var(--motion-glide, ease-out);
 	}
 
-	.vp-night-btn:hover {
+	.vp-night-btn:hover,
+	.vp-theater-btn:hover {
 		color: var(--color-base-content);
 	}
 
-	.vp-night-btn:focus-visible {
+	.vp-night-btn:focus-visible,
+	.vp-theater-btn:focus-visible {
 		outline: 2px solid var(--color-primary);
 		outline-offset: 1px;
 	}
@@ -4755,6 +5003,11 @@
 		color: var(--color-warning);
 	}
 
+	/* Theater (jatui-ee2ty): lit in the primary while the page is widened. */
+	.vp-theater-btn.active {
+		color: var(--color-primary);
+	}
+
 	/* Under reduced motion the veil still dims — the dimming IS the feature —
 	   but the long 900ms/1200ms ramps shrink to a short luminance fade. A
 	   change in brightness is not motion, and a hard step every tick would be
@@ -4773,7 +5026,8 @@
 			transition-duration: 120ms;
 		}
 
-		.vp-night-btn {
+		.vp-night-btn,
+		.vp-theater-btn {
 			transition: none;
 		}
 	}

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

@@ -163,7 +163,35 @@ 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;
+    /**
+     * A reader who scrolled the transcript pane pauses its follow; after
+     * this long with the pane left alone while playing, follow resumes by
+     * itself (ms, default 6000; 0 ⇒ only a seek, a line/chapter click,
+     * play after pause or the "Resume following" pill bring it back).
+     */
+    followResumeMs?: number;
+    /**
+     * Theater mode (jatui-ee2ty) — bindable. NOT fullscreen: the player
+     * only says it wants the page's width; the HOST lays its page out
+     * full-width (`bind:theater` or `onTheaterChange`). The player itself
+     * marks its root `vp-theater` / `data-theater` and puts a side
+     * transcript below the video. The control-bar button and `t` toggle
+     * it; the choice is remembered per viewer under the `player.theater`
+     * setting — through `settingsStore` when one is given, else this
+     * browser's localStorage (every access guarded). The prop is the
+     * host's default; a remembered choice wins.
+     */
+    theater?: boolean;
+    /** Show the theater button + `t` key (video only; default true). */
+    theaterButton?: boolean;
+    /** The viewer toggled theater mode (button, `t`, settings panel). */
+    onTheaterChange?: (theater: boolean) => void;
     crossorigin?: 'anonymous' | 'use-credentials' | null;
     syncUrlTime?: boolean;
     /**
@@ -419,6 +447,6 @@ type $$ComponentProps = {
 declare const VideoPlayer: import("svelte").Component<$$ComponentProps, {
     bandState: () => BandState;
     seekToTime: (sec: number) => void;
-}, "night" | "nightDepth">;
+}, "night" | "theater" | "nightDepth">;
 type VideoPlayer = ReturnType<typeof VideoPlayer>;
 export default VideoPlayer;

package/dist/components/basic/JumpToLatest.svelte

@@ -19,11 +19,14 @@
 		visible = false,
 		unreadCount = 0,
 		label = 'Jump to latest',
+		text = '',
 		onclick
 	}: {
 		visible?: boolean;
 		unreadCount?: number;
 		label?: string;
+		/** Visible words beside the arrow (default none — icon only). Keep it a prefix of `label`. */
+		text?: string;
 		onclick?: () => void;
 	} = $props();
 </script>
@@ -41,6 +44,7 @@
 				<span class="font-semibold tabular-nums">{unreadCount}</span>
 				<span>new</span>
 			{/if}
+			{#if text}<span>{text}</span>{/if}
 			<svg
 				xmlns="http://www.w3.org/2000/svg"
 				class="size-4"

package/dist/components/basic/JumpToLatest.svelte.d.ts

@@ -2,6 +2,8 @@ type $$ComponentProps = {
     visible?: boolean;
     unreadCount?: number;
     label?: string;
+    /** Visible words beside the arrow (default none — icon only). Keep it a prefix of `label`. */
+    text?: string;
     onclick?: () => void;
 };
 declare const JumpToLatest: import("svelte").Component<$$ComponentProps, {}, "">;

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;
@@ -86,6 +87,12 @@ export interface BandPaintState {
         marker: string;
         /** The light ribbon's wash (FEATURES.md: amber). Defaults to `marker`. */
         ribbon?: string;
+        /**
+         * The hovered chapter's span (jatui-ee2ty) — the theme's `accent`, so
+         * it reads as a different colour from the played (primary) envelope.
+         * Defaults to `accent` (this state's primary).
+         */
+        chapter?: string;
         /** Comment dots. Defaults to `accent`. */
         comment?: string;
         /** Like heat strip. Defaults to `accent`. */
@@ -111,6 +118,21 @@ 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;
+/** Width of the full-height edge lines at a lit chapter's bounds, px. */
+export declare const LIT_EDGE_W = 2;
+/** Opacity of the lit chapter's fill — clearly visible on light and dark themes. */
+export declare const LIT_FILL_ALPHA = 0.35;
+/**
+ * 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,24 @@ export function paintBand(ctx, W, H, s) {
         }
         ctx.globalAlpha = 1;
     }
+    // The lit chapter (jatui-ap4oz, strengthened in jatui-ee2ty): the whole
+    // column in the chapter colour at LIT_FILL_ALPHA, full-height edge lines
+    // at its bounds and a rule along the top — 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) {
+        const w = lit.x1 - lit.x0;
+        ctx.fillStyle = s.colors.chapter ?? accent;
+        ctx.globalAlpha = LIT_FILL_ALPHA;
+        ctx.fillRect(lit.x0, 0, w, H);
+        ctx.globalAlpha = 0.95;
+        ctx.fillRect(lit.x0, 0, w, LIT_RULE_H);
+        const e = Math.min(LIT_EDGE_W, w / 2);
+        ctx.fillRect(lit.x0, 0, e, H);
+        ctx.fillRect(lit.x1 - e, 0, e, H);
+        ctx.globalAlpha = 1;
+    }
     const p = s.peaks;
     const withWave = !!p;
     const n = p?.length ?? 0;
@@ -310,6 +328,26 @@ 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;
+/** Width of the full-height edge lines at a lit chapter's bounds, px. */
+export const LIT_EDGE_W = 2;
+/** Opacity of the lit chapter's fill — clearly visible on light and dark themes. */
+export const LIT_FILL_ALPHA = 0.35;
+/**
+ * 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/keys.d.ts

@@ -5,7 +5,8 @@
  *
  * Map parity is with extension-library's theater handler (FEATURES.md):
  * Space play/pause, ←/→ seek, ↑/↓ volume, M mute, −/= speed, Backspace reset
- * speed, </> frame step, [/] chapter jumps, B bookmark, T transcript, ?
+ * speed, </> frame step, [/] chapter jumps, B bookmark, Shift+T transcript
+ * (t is theater mode, YouTube's key — jatui-ee2ty), ?
  * shortcuts, Home/End. Deliberately NOT ported: F/M (favourite/file-under —
  * library-app verbs, not player verbs), `/` (transcript search — the pane
  * has none yet). N (night cycle) landed with the night module (mos-5lzns.33)
@@ -20,7 +21,7 @@ export interface PlayerKeyRow {
      * Availability gate: the row is only advertised (and the key only bound)
      * when the feature's data exists. Undefined ⇒ always active.
      */
-    when?: 'chapters' | 'rail' | 'bookmarks' | 'transcript' | 'comments' | 'night' | 'settings';
+    when?: 'chapters' | 'rail' | 'bookmarks' | 'transcript' | 'comments' | 'night' | 'settings' | 'theater';
 }
 /** Order follows the help overlay: transport, seek, volume, speed, structure. */
 export declare const PLAYER_KEYS: PlayerKeyRow[];

package/dist/video/keys.js

@@ -5,7 +5,8 @@
  *
  * Map parity is with extension-library's theater handler (FEATURES.md):
  * Space play/pause, ←/→ seek, ↑/↓ volume, M mute, −/= speed, Backspace reset
- * speed, </> frame step, [/] chapter jumps, B bookmark, T transcript, ?
+ * speed, </> frame step, [/] chapter jumps, B bookmark, Shift+T transcript
+ * (t is theater mode, YouTube's key — jatui-ee2ty), ?
  * shortcuts, Home/End. Deliberately NOT ported: F/M (favourite/file-under —
  * library-app verbs, not player verbs), `/` (transcript search — the pane
  * has none yet). N (night cycle) landed with the night module (mos-5lzns.33)
@@ -30,7 +31,9 @@ export const PLAYER_KEYS = [
     // and "people's reactions to it" sit under one hand (mos-5lzns.30).
     { keys: '{ / }', description: 'Previous / next comment', when: 'comments' },
     { keys: 'B', description: 'Bookmark at the current time', when: 'bookmarks' },
-    { keys: 'T', description: 'Show / hide the transcript', when: 'transcript' },
+    // t = theater, YouTube's key; the transcript moved to Shift+T (jatui-ee2ty).
+    { keys: 't', description: 'Theater mode on / off', when: 'theater' },
+    { keys: 'Shift+T', description: 'Show / hide the transcript', when: 'transcript' },
     { keys: 'N', description: 'Night dimming: auto / on / off', when: 'night' },
     { keys: 'Home / End', description: 'Jump to start / end' },
     { keys: ',', description: 'Settings', when: 'settings' },

package/dist/video/settings/registry.d.ts

@@ -37,7 +37,7 @@ export type SettingValue = boolean | number | string;
  * a switch that does nothing. The component resolves them (see
  * `SettingAvailability`); the registry only names them.
  */
-export type SettingWhen = 'waveform' | 'speakers' | 'ads' | 'loudness' | 'quiet' | 'limiter' | 'night' | 'nightLuma' | 'flashes' | 'windDown' | 'idle' | 'resume' | 'open';
+export type SettingWhen = 'waveform' | 'speakers' | 'ads' | 'loudness' | 'quiet' | 'limiter' | 'night' | 'nightLuma' | 'flashes' | 'windDown' | 'idle' | 'resume' | 'open' | 'theater';
 export type SettingAvailability = Partial<Record<SettingWhen, boolean>>;
 export interface SettingOption {
     value: string;

package/dist/video/settings/registry.js

@@ -281,6 +281,18 @@ export const VIDEO_SETTINGS = [
         hint: 'One time axis instead of two. The waveform is always on screen and already seeks, so the progress bar stands down and hands it the job — and comes back as an overview while the waveform is zoomed. Turn this off to keep both bars.',
         owner: 'mos-5lzns.30',
         wired: true
+    },
+    {
+        id: 'player.theater',
+        group: 'Playback',
+        label: 'Theater mode',
+        type: 'bool',
+        default: false,
+        prop: 'theater',
+        when: 'theater',
+        hint: "Widens the player to the page's full width — not fullscreen, so the rest of the page is still there below it — and puts a side transcript underneath. t toggles it, and the player remembers your choice.",
+        owner: 'jatui-ee2ty',
+        wired: true
     }
 ];
 const BY_ID = new Map(VIDEO_SETTINGS.map((s) => [s.id, s]));

package/dist/video/settings/store.d.ts

@@ -46,6 +46,14 @@ export interface SettingsSessionOpts {
 }
 export declare const SETTINGS_WRITE_DELAY_MS = 400;
 export declare function createSettingsSession(opts: SettingsSessionOpts): SettingsSession;
+/**
+ * This browser's localStorage as a settings store, one entry per id under
+ * `prefix` (jatui-ee2ty) — the fallback VideoPlayer uses for `player.theater`
+ * when the host gives no `settingsStore`. Every access is guarded: no
+ * storage (SSR, a private window, blocked site data) reads as nothing stored
+ * and drops writes; it never throws.
+ */
+export declare function localSettingsStore(prefix?: string): VideoSettingsStore;
 /**
  * A plain in-memory store — for demos and tests, and for a host that wants
  * to hold the values itself (read them back with `.values`).

package/dist/video/settings/store.js

@@ -100,6 +100,42 @@ export function createSettingsSession(opts) {
         }
     };
 }
+/**
+ * This browser's localStorage as a settings store, one entry per id under
+ * `prefix` (jatui-ee2ty) — the fallback VideoPlayer uses for `player.theater`
+ * when the host gives no `settingsStore`. Every access is guarded: no
+ * storage (SSR, a private window, blocked site data) reads as nothing stored
+ * and drops writes; it never throws.
+ */
+export function localSettingsStore(prefix = 'jatui.video.') {
+    const ls = () => {
+        try {
+            return typeof localStorage === 'undefined' ? null : localStorage;
+        }
+        catch {
+            return null;
+        }
+    };
+    return {
+        get(id) {
+            try {
+                const raw = ls()?.getItem(prefix + id);
+                return raw == null ? undefined : JSON.parse(raw);
+            }
+            catch {
+                return undefined;
+            }
+        },
+        set(id, v) {
+            try {
+                ls()?.setItem(prefix + id, JSON.stringify(v));
+            }
+            catch {
+                /* full or blocked — the choice lasts while the player does */
+            }
+        }
+    };
+}
 /**
  * A plain in-memory store — for demos and tests, and for a host that wants
  * to hold the values itself (read them back with `.values`).

package/dist/video/transcriptFollow.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 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 (jatui-ee2ty): a wheel, touch drag, page key or scrollbar
+ * grab inside the pane counts only when the PANE's own scrollTop moves as
+ * its result — a wheel over the pane that scrolls the page is not reading
+ * the transcript. Follow then pauses until it is asked back (the "Resume
+ * following" pill, clicking a line, a seek, play after pause) or the reader
+ * has left the pane alone for a few seconds while it plays. The follow's own
+ * scrolls and the windowing's height corrections are never intent.
+ */
+/**
+ * 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;
+/** How long after a gesture a pane scroll still counts as its result, ms. */
+export declare const INTENT_WINDOW_MS = 300;
+/** How long a programmatic (follow) scroll may take to land, ms — smooth scrolls animate. */
+export declare const PROGRAMMATIC_WINDOW_MS = 700;
+/** Default idle time in a paused pane, while playing, before follow resumes itself, ms. */
+export declare const FOLLOW_RESUME_IDLE_MS = 6000;
+export interface ReaderScrollWatch {
+    /** Stop listening. */
+    (): void;
+    /**
+     * The player is about to scroll the pane itself (follow, windowed jump).
+     * Scrolls until it lands — or until the reader's next gesture, which the
+     * browser lets interrupt it — are never intent.
+     */
+    programmatic(): void;
+}
+/**
+ * Listen for reader scroll intent on `pane`; `onIntent` fires on each one
+ * (jatui-ee2ty).
+ *
+ * A gesture alone is NOT intent. Wheel, touch drag, the page keys and a
+ * scrollbar grab only ARM the watch with the pane's scrollTop at that
+ * moment; intent is the pane's OWN scrollTop then moving within
+ * `INTENT_WINDOW_MS` (or while the scrollbar is held). A wheel over the pane
+ * that chains to the page — the pane at its boundary, or the browser latched
+ * onto the window — leaves scrollTop where it was, so follow stays on. The
+ * player's own scrolls are fenced off with `programmatic()`.
+ */
+export declare function watchReaderScroll(pane: HTMLElement, onIntent: () => void, opts?: {
+    windowMs?: number;
+    now?: () => number;
+}): ReaderScrollWatch;

package/dist/video/transcriptFollow.js

@@ -0,0 +1,140 @@
+/**
+ * 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 (jatui-ee2ty): a wheel, touch drag, page key or scrollbar
+ * grab inside the pane counts only when the PANE's own scrollTop moves as
+ * its result — a wheel over the pane that scrolls the page is not reading
+ * the transcript. Follow then pauses until it is asked back (the "Resume
+ * following" pill, clicking a line, a seek, play after pause) or the reader
+ * has left the pane alone for a few seconds while it plays. The follow's own
+ * scrolls and the windowing's height corrections are never intent.
+ */
+/**
+ * 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']);
+/** How long after a gesture a pane scroll still counts as its result, ms. */
+export const INTENT_WINDOW_MS = 300;
+/** How long a programmatic (follow) scroll may take to land, ms — smooth scrolls animate. */
+export const PROGRAMMATIC_WINDOW_MS = 700;
+/** Default idle time in a paused pane, while playing, before follow resumes itself, ms. */
+export const FOLLOW_RESUME_IDLE_MS = 6000;
+/**
+ * Listen for reader scroll intent on `pane`; `onIntent` fires on each one
+ * (jatui-ee2ty).
+ *
+ * A gesture alone is NOT intent. Wheel, touch drag, the page keys and a
+ * scrollbar grab only ARM the watch with the pane's scrollTop at that
+ * moment; intent is the pane's OWN scrollTop then moving within
+ * `INTENT_WINDOW_MS` (or while the scrollbar is held). A wheel over the pane
+ * that chains to the page — the pane at its boundary, or the browser latched
+ * onto the window — leaves scrollTop where it was, so follow stays on. The
+ * player's own scrolls are fenced off with `programmatic()`.
+ */
+export function watchReaderScroll(pane, onIntent, opts = {}) {
+    const windowMs = opts.windowMs ?? INTENT_WINDOW_MS;
+    const now = opts.now ?? (() => (typeof performance !== 'undefined' ? performance.now() : Date.now()));
+    let armedUntil = -Infinity;
+    let armedTop = 0;
+    let held = false;
+    let progUntil = -Infinity;
+    const armed = () => held || now() <= armedUntil;
+    const arm = () => {
+        // The reader's gesture interrupts any smooth follow scroll in flight:
+        // from here on, movement is theirs.
+        progUntil = -Infinity;
+        if (!armed())
+            armedTop = pane.scrollTop;
+        armedUntil = now() + windowMs;
+    };
+    const onScroll = () => {
+        if (now() <= progUntil) {
+            armedTop = pane.scrollTop; // the player moved it — re-base
+            return;
+        }
+        if (!armed())
+            return;
+        if (Math.abs(pane.scrollTop - armedTop) >= 1) {
+            armedUntil = -Infinity;
+            armedTop = pane.scrollTop;
+            onIntent();
+        }
+    };
+    const key = (e) => {
+        if (SCROLL_KEYS.has(e.key))
+            arm();
+    };
+    // 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) {
+            arm();
+            held = true;
+        }
+    };
+    const up = () => {
+        if (!held)
+            return;
+        held = false;
+        armedUntil = now() + windowMs; // the last drag frame's scroll still counts
+    };
+    pane.addEventListener('wheel', arm, { passive: true });
+    pane.addEventListener('touchmove', arm, { passive: true });
+    pane.addEventListener('keydown', key);
+    pane.addEventListener('pointerdown', down);
+    pane.addEventListener('scroll', onScroll, { passive: true });
+    if (typeof window !== 'undefined')
+        window.addEventListener('pointerup', up);
+    const stop = (() => {
+        pane.removeEventListener('wheel', arm);
+        pane.removeEventListener('touchmove', arm);
+        pane.removeEventListener('keydown', key);
+        pane.removeEventListener('pointerdown', down);
+        pane.removeEventListener('scroll', onScroll);
+        if (typeof window !== 'undefined')
+            window.removeEventListener('pointerup', up);
+    });
+    stop.programmatic = () => {
+        progUntil = now() + PROGRAMMATIC_WINDOW_MS;
+    };
+    return stop;
+}

package/package.json

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