@joewinke/jatui 0.38.3 → 0.38.5

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'`), `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?` |
+| `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; a wheel/keyboard volume change also flashes a clear volume OSD — glyph, level bar and %, "Muted" at 0, opacity-only fade) 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,7 +86,12 @@
 	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 {
+		scrollRowIntoPane,
+		watchReaderScroll,
+		FOLLOW_RESUME_IDLE_MS,
+		type ReaderScrollWatch
+	} from '../video/transcriptFollow';
 	import JumpToLatest from './basic/JumpToLatest.svelte';
 	import type {
 		VideoBookmark,
@@ -241,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,
@@ -275,6 +283,10 @@
 		startAt = null,
 		transcriptPosition = 'below',
 		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
@@ -439,6 +451,29 @@
 		 * 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;
 		/**
@@ -774,6 +809,7 @@
 		if (!v) return;
 		v.muted = !v.muted;
 		if (!v.muted && v.volume === 0) v.volume = 0.5;
+		showVolumeOsd(v.volume, v.muted);
 	}
 	function onVolumeInput(e: Event) {
 		const v = videoEl;
@@ -781,6 +817,7 @@
 		const next = Number((e.currentTarget as HTMLInputElement).value);
 		v.volume = Math.min(1, Math.max(0, next));
 		v.muted = next === 0;
+		showVolumeOsd(v.volume, v.muted);
 	}
 	function toggleFullscreen() {
 		if (typeof document === 'undefined') return;
@@ -823,6 +860,16 @@
 	let osd = $state(''); // transient wheel/keyboard readout (volume / seek / speed)
 	let osdOn = $state(false);
 
+	// ── Volume OSD (jatui-pu698) ────────────────────────────────────────────
+	// Wheel/keyboard volume feedback: a speaker glyph + horizontal level bar
+	// + % value (or "Muted" at 0), floated over the stage. Distinct from the
+	// tiny corner readout: a volume change is a physical gesture that deserves
+	// to be SEEN, not just a number blink.
+	let volOsdOn = $state(false);
+	let volOsdVolume = $state(0);
+	let volOsdMuted = $state(false);
+	let volOsdTimer: ReturnType<typeof setTimeout> | null = null;
+
 	// ── Speaker filter state ────────────────────────────────────────────────
 	let soloKey = $state(ALL_KEY);
 	let mutedKeys = $state(new Set<string>());
@@ -859,8 +906,20 @@
 	});
 
 	let transcriptEl: HTMLDivElement | null = null;
-	/** The reader scrolled the pane themselves — auto-follow waits for "Jump to current". */
+	/** 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);
@@ -890,7 +949,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
@@ -1037,7 +1096,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
 		}
 	}
 
@@ -1057,13 +1116,16 @@
 			scheduleRowMeasure();
 		});
 		ro.observe(el);
-		const unwatch = watchReaderScroll(el, () => {
+		const watch = watchReaderScroll(el, () => {
+			lastReaderScrollAt = performance.now();
 			if (activeSegment) followPaused = true;
 		});
+		readerWatch = watch;
 		return {
 			destroy() {
 				ro.disconnect();
-				unwatch();
+				watch();
+				if (readerWatch === watch) readerWatch = null;
 				transcriptEl = null;
 			}
 		};
@@ -1228,6 +1290,7 @@
 			cache: layerCache,
 			colors: {
 				accent: getDaisyUIColor('primary'),
+				chapter: getDaisyUIColor('accent') || getDaisyUIColor('primary'),
 				neutral: getDaisyUIColor('base-content'),
 				marker: getDaisyUIColor('warning'),
 				ribbon: getDaisyUIColor('warning'),
@@ -1295,6 +1358,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;
 		})
 	);
@@ -1330,6 +1394,24 @@
 		zoomTimer = setTimeout(() => (zoomLabelOn = false), 900);
 	}
 
+	// ── Volume OSD (jatui-pu698) ────────────────────────────────────────────
+	// Big, legible volume indicator: speaker glyph + level bar + % ("Muted" at
+	// 0). Replaces the tiny corner badge for wheel/keyboard volume gestures.
+	// Shares `osdTimer` with the plain OSD so only ONE readout floats at a
+	// time, and any pending plain flash is superseded (not queued behind).
+	function showVolumeOsd(volume: number, muted: boolean) {
+		if (volOsdTimer) clearTimeout(volOsdTimer);
+		if (osdTimer) {
+			clearTimeout(osdTimer);
+			osdTimer = null;
+		}
+		osdOn = false; // only one readout at a time
+		volOsdVolume = volume;
+		volOsdMuted = muted;
+		volOsdOn = true;
+		volOsdTimer = setTimeout(() => (volOsdOn = false), 800);
+	}
+
 	function flashOsd(text: string, ms = 900) {
 		if (osdTimer) clearTimeout(osdTimer);
 		if (!text || ms <= 0) {
@@ -1347,6 +1429,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) ──────────────────
@@ -2171,6 +2254,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;
 	}
 
@@ -2193,6 +2284,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);
@@ -2212,7 +2327,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. */
@@ -2236,7 +2352,8 @@
 			idleDetection,
 			resumeSnap,
 			openMotion,
-			oneAxis
+			oneAxis,
+			theater: theaterOn
 		};
 		const out: Record<string, SettingValue> = {};
 		for (const spec of VIDEO_SETTINGS) {
@@ -2700,7 +2817,7 @@
 		const next = Math.min(1, Math.max(0, videoEl.volume - Math.sign(e.deltaY) * 0.05));
 		videoEl.volume = next;
 		if (next > 0) videoEl.muted = false;
-		flashOsd(`${Math.round(next * 100)}%`);
+		showVolumeOsd(next, next === 0);
 	}
 
 	/**
@@ -2766,15 +2883,15 @@
 			case 'ArrowUp':
 				v.volume = Math.min(1, v.volume + 0.05);
 				if (v.volume > 0) v.muted = false;
-				flashOsd(`${Math.round(v.volume * 100)}%`);
+				showVolumeOsd(v.volume, v.muted);
 				break;
 			case 'ArrowDown':
 				v.volume = Math.max(0, v.volume - 0.05);
-				flashOsd(`${Math.round(v.volume * 100)}%`);
+				showVolumeOsd(v.volume, v.muted);
 				break;
 			case 'm':
 				v.muted = !v.muted;
-				flashOsd(v.muted ? 'Muted' : `${Math.round(v.volume * 100)}%`);
+				showVolumeOsd(v.volume, v.muted);
 				break;
 			case '-':
 			case '_':
@@ -2838,6 +2955,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();
@@ -2929,7 +3052,7 @@
 		if (!pane) return;
 		const node = rowRefs[seg.id];
 		if (node) {
-			scrollRowIntoPane(pane, node, !reduceMotion);
+			scrollPaneTo(pane, node);
 			return;
 		}
 		if (!transVirtual) return;
@@ -2937,7 +3060,7 @@
 		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);
+		paneScrollTop(pane, Math.max(0, top + transPadTop - Math.max(0, vpHeight) / 3));
 		pendingAutoScrollId = seg.id;
 	}
 
@@ -2954,9 +3077,32 @@
 		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) {
-		followPaused = false;
 		seekTo(seg.startSec);
 	}
 
@@ -2985,7 +3131,7 @@
 			const node = rowRefs[id];
 			if (!node) return;
 			pendingAutoScrollId = null;
-			if (transcriptEl && !followPaused) scrollRowIntoPane(transcriptEl, node, !reduceMotion);
+			if (transcriptEl && !followPaused) scrollPaneTo(transcriptEl, node);
 		});
 	});
 
@@ -3013,10 +3159,13 @@
 <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}
+	class:vp-vol-flash={volOsdOn}
 	class:vp-audio={isAudio}
 	class:vp-night-capable={nightPresent}
 	class:vp-night-surround={surroundMix > 0.001}
@@ -3081,6 +3230,7 @@
 					if (nightPresent || guardPresent) nightTick();
 				}}
 				onplay={() => {
+					resumeFollow();
 					if (nightPresent || guardPresent) nightTick();
 					if (windPhase === 'paused') windCancel();
 					if (windOn) windProbe();
@@ -3136,10 +3286,41 @@
 				<div class="vp-wind-veil" aria-hidden="true"></div>
 			{/if}
 			<div class="vp-osd" class:on={osdOn} aria-hidden="true">{osd}</div>
-		</div>
-		</div>
+			<!-- Volume OSD (jatui-pu698): speaker glyph + level bar + %, centred
+			     near the top of the stage so a wheel/keyboard volume gesture is
+			     SEEN, not just a corner number blink. aria-hidden: the volume
+			     slider itself already reports the value to AT. -->
+			<div class="vp-volume-osd" class:on={volOsdOn} aria-hidden="true">
+				<svg
+						class="vp-vol-glyph"
+						viewBox="0 0 24 24"
+						width="24"
+						height="24"
+						fill="none"
+						stroke="currentColor"
+						stroke-width="1.8"
+						stroke-linecap="round"
+						stroke-linejoin="round"
+					>
+						<path d="M4 9.5h3.5L12 5.5v13l-4.5-4H4z" fill="currentColor" stroke="none" />
+						{#if volOsdMuted || volOsdVolume === 0}
+							<path d="M16 9.5l5 5M21 9.5l-5 5" />
+						{:else}
+							<path d="M15.5 9a4 4 0 0 1 0 6" />
+							{#if volOsdVolume > 0.5}<path d="M18 6.5a7.5 7.5 0 0 1 0 11" />{/if}
+						{/if}
+					</svg>
+					<span class="vp-vol-bar">
+						<span class="vp-vol-fill" style="width: {Math.round(volOsdVolume * 100)}%"></span>
+					</span>
+					<span class="vp-vol-text">
+						{volOsdMuted || volOsdVolume === 0 ? 'Muted' : `${Math.round(volOsdVolume * 100)}%`}
+					</span>
+				</div>
+			</div>
+			</div>
 
-		<!-- The band: one time axis for the envelope, chapters, speakers and
+			<!-- The band: one time axis for the envelope, chapters, speakers and
 		     bookmarks. Its height is reserved from the first frame, so data
 		     arriving late fades into already-owned space. -->
 		<div
@@ -3230,7 +3411,34 @@
 			{#if isAudio}
 				<!-- No stage to float the readout over: it rides the band. -->
 				<div class="vp-osd vp-osd-band" class:on={osdOn} aria-hidden="true">{osd}</div>
-			{/if}
+				<div class="vp-volume-osd vp-volume-osd-band" class:on={volOsdOn} aria-hidden="true">
+					<svg
+							class="vp-vol-glyph"
+							viewBox="0 0 24 24"
+							width="24"
+							height="24"
+							fill="none"
+							stroke="currentColor"
+							stroke-width="1.8"
+							stroke-linecap="round"
+							stroke-linejoin="round"
+						>
+							<path d="M4 9.5h3.5L12 5.5v13l-4.5-4H4z" fill="currentColor" stroke="none" />
+							{#if volOsdMuted || volOsdVolume === 0}
+								<path d="M16 9.5l5 5M21 9.5l-5 5" />
+							{:else}
+								<path d="M15.5 9a4 4 0 0 1 0 6" />
+								{#if volOsdVolume > 0.5}<path d="M18 6.5a7.5 7.5 0 0 1 0 11" />{/if}
+							{/if}
+						</svg>
+						<span class="vp-vol-bar">
+							<span class="vp-vol-fill" style="width: {Math.round(volOsdVolume * 100)}%"></span>
+						</span>
+						<span class="vp-vol-text">
+							{volOsdMuted || volOsdVolume === 0 ? 'Muted' : `${Math.round(volOsdVolume * 100)}%`}
+						</span>
+					</div>
+				{/if}
 
 			{#if hover}
 				<div
@@ -3285,6 +3493,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"
@@ -3628,7 +3853,8 @@
 		</div>
 		<JumpToLatest
 			visible={followPaused && activeSegment != null}
-			label="Jump to current"
+			label="Resume following"
+			text="Resume following"
 			onclick={jumpToCurrent}
 		/>
 		</div>
@@ -4009,6 +4235,64 @@
 		opacity: 1;
 	}
 
+	/* ── Volume OSD (jatui-pu698) ───────────────────────────────────────── */
+	/* Wheel/keyboard volume feedback: speaker glyph + level bar + %, centred
+	   near the top of the stage so a gesture is SEEN, not just a corner number
+	   blink. Token surface with backdrop so it is legible on any frame. The
+	   flash is purely opacity — no slide — so it is reduced-motion safe. */
+	.vp-volume-osd {
+		position: absolute;
+		top: 10%;
+		left: 50%;
+		transform: translateX(-50%);
+		display: flex;
+		align-items: center;
+		gap: 10px;
+		padding: 10px 16px;
+		border-radius: 999px;
+		background: color-mix(in oklch, var(--color-base-100) 85%, transparent);
+		backdrop-filter: blur(8px);
+		color: var(--color-base-content);
+		font-size: 0.9rem;
+		font-weight: 600;
+		font-variant-numeric: tabular-nums;
+		pointer-events: none;
+		opacity: 0;
+		transition: opacity var(--motion-enter, 200ms) var(--motion-glide, ease-out);
+		z-index: 10;
+		box-shadow: 0 4px 16px color-mix(in oklch, black 20%, transparent);
+	}
+
+	.vp-volume-osd.on {
+		opacity: 1;
+	}
+
+	.vp-vol-glyph {
+		flex: none;
+		opacity: 0.9;
+	}
+
+	.vp-vol-bar {
+		display: block;
+		width: 80px;
+		height: 4px;
+		border-radius: 999px;
+		background: color-mix(in oklch, var(--color-base-content) 20%, transparent);
+		overflow: hidden;
+	}
+
+	.vp-vol-fill {
+		display: block;
+		height: 100%;
+		background: var(--color-primary);
+		border-radius: 999px;
+		transition: width 150ms ease-out;
+	}
+
+	.vp-vol-text {
+		min-width: 3.5rem;
+	}
+
 	/* The band owns its height from the first frame so a waveform or speaker
 	   turns arriving minutes in fade into space that is already theirs. */
 	.vp-band {
@@ -4025,6 +4309,17 @@
 		opacity: 1;
 	}
 
+	/* Volume flash (jatui-pu698): reveal the transport and its volume slider
+	   on a wheel/keyboard volume change. */
+	.vp-vol-flash .vp-transport {
+		opacity: 1;
+		visibility: visible;
+	}
+
+	.vp-vol-flash .vp-volume {
+		opacity: 1;
+	}
+
 	/* Audio: no picture, so no stage at all. The element still plays. */
 	.vp-stage-audio {
 		display: none;
@@ -4691,6 +4986,7 @@
 	@media (prefers-reduced-motion: reduce) {
 		.vp-band,
 		.vp-osd,
+		.vp-volume-osd,
 		.vp-zoom,
 		.vp-lane-span,
 		.vp-chip,
@@ -4836,7 +5132,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;
@@ -4849,11 +5146,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;
 	}
@@ -4863,6 +5162,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
@@ -4881,7 +5185,8 @@
 			transition-duration: 120ms;
 		}
 
-		.vp-night-btn {
+		.vp-night-btn,
+		.vp-theater-btn {
 			transition: none;
 		}
 	}

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

@@ -169,6 +169,29 @@ type $$ComponentProps = {
      * 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;
     /**
@@ -424,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

@@ -87,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`. */
@@ -114,6 +120,10 @@ export declare function prepareCanvas(canvas: HTMLCanvasElement): CanvasRenderin
 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

package/dist/video/band.js

@@ -161,17 +161,22 @@ 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
+    // 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) {
-        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);
+        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;
@@ -325,6 +330,10 @@ export function paintBand(ctx, W, H, s) {
 }
 /** 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

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

@@ -8,12 +8,13 @@
  * 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.
+ * 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
@@ -26,7 +27,35 @@ export declare function nearestScrollTop(rowTop: number, rowBottom: number, scro
  * 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.
+ * 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): () => void;
+export declare function watchReaderScroll(pane: HTMLElement, onIntent: () => void, opts?: {
+    windowMs?: number;
+    now?: () => number;
+}): ReaderScrollWatch;

package/dist/video/transcriptFollow.js

@@ -8,12 +8,13 @@
  * 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.
+ * 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
@@ -52,29 +53,88 @@ export function scrollRowIntoPane(pane, row, smooth, margin = 8) {
 // 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.
+ * 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) {
-    const wheel = () => onIntent();
-    const touch = () => onIntent();
+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))
-            onIntent();
+            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)
-            onIntent();
+        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', wheel, { passive: true });
-    pane.addEventListener('touchmove', touch, { passive: true });
+    pane.addEventListener('wheel', arm, { passive: true });
+    pane.addEventListener('touchmove', arm, { passive: true });
     pane.addEventListener('keydown', key);
     pane.addEventListener('pointerdown', down);
-    return () => {
-        pane.removeEventListener('wheel', wheel);
-        pane.removeEventListener('touchmove', touch);
+    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.3",
+  "version": "0.38.5",
   "private": false,
   "description": "Shared Svelte 5 component library for JAT projects",
   "type": "module",