@joewinke/jatui 0.38.5 → 0.38.6

package/CLAUDE.md

@@ -119,7 +119,7 @@ Item-by-item review surfaces (MOS review-ux, design mos-z8vgx). One `VerdictOpti
 | `ThumbnailGrid` | Generic thumbnail strip (chimaro port) — image tiles with text-tile fallback, +N overflow counter, remove/add affordances. Decoupled from any media library: pass `{id, url, alt}` items, or a `cell` snippet for full control of tile contents. `removeMode` — `'hover'` (default) reveals the × on hover/focus and keeps it visible on coarse (touch) pointers (ContextMenuTrigger pattern); `'always'` pins it for touch-first flows. `gridCols` (e.g. `'grid-cols-2 sm:grid-cols-4'`) switches the strip to a responsive CSS grid with column-filling tiles. | `items: ThumbnailItem[]`, `max`, `size` (`xs\|sm\|md\|lg`), `removable`+`onRemove`, `removeMode` (`hover\|always`), `addable`+`onAdd`, `onSelect`, `gridCols`, `class`, `cell` snippet |
 | `MediaWorkbench` | Full-featured image editor modal — upload, AI generate, AI edit, background removal, annotation canvas. **Preferred over `SmartImageEditor` for new image fields.** Two-column modal: preview left, 4 action tabs right (Generate, Edit, Remove BG, Annotate). Save uploads blob to `uploadEndpoint` or emits `onComplete`. Requires proxy endpoints from jst-23w1l.2. | `value` (bindable `string \| null`), `uploadEndpoint?` (default `/api/media`), `onComplete?`, `accept?` |
 | `MediaLightbox` | Full-screen media preview — z-9040 backdrop, arrow-key paging when given an array, `+/-/0` zoom, download action, Escape/backdrop close. **Use this for the general "just show it big" case** — replaces hand-rolled `fixed inset-0 z-[9040]` modals. For annotated / markup-overlaid image previews, use `ImageLightbox` instead. | `src?`, `filename?`, `kind?: 'image' \| 'video'`, `downloadUrl?`, `items?: MediaItem[]`, `initialIndex?`, `onClose?`, `zIndex?` |
-| `VideoPlayer` | **The default video surface — reach for this over a bare `<video controls>`.** One timeline band carrying a waveform-envelope scrubber, chapter flags (top edge), bookmark diamonds (bottom edge), diarized speaker colouring and scroll-to-zoom, plus an optional transcript pane (click to seek, active line auto-scroll, solo/skip per speaker, `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?` |
+| `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; Shift+wheel over the transcript steps line by line (a plain wheel over the transcript scrolls the pane natively — the page is never trapped). 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

@@ -167,6 +167,12 @@
 	import { dragCancel, dragEnd, dragMove, dragStart, type DragState } from '../video/band/drag';
 	import { createBandLayerCache } from '../video/band/memo';
 	import { BAND_KEYS, PLAYER_KEYS, chapterJump, FRAME_STEP_SEC } from '../video/keys';
+	import {
+		highlightRowHtml,
+		lineScrubTarget,
+		pickMatch,
+		transcriptWheelDecision
+	} from '../video/transcriptSearch';
 	import {
 		adMaxStep,
 		adSkipTarget,
@@ -887,6 +893,18 @@
 	let transcriptVisible = $state(true);
 	let keysOpen = $state(false);
 
+	// ── Transcript search (jatui-xmtnv) ────────────────────────────────
+	// `/` opens a search box over the transcript pane; matches highlight in
+	// place, Enter jumps to the next match (Shift+Enter back), Esc closes.
+	// The page omnibar's own `/` yields while focus is inside the player:
+	// the claiming keydown's propagation is stopped, and the search box
+	// stops its own keydowns so typing never leaks into the player map or
+	// the page.
+	let searchOpen = $state(false);
+	let searchQuery = $state('');
+	let searchMatchIdx = $state(-1);
+	let searchInputEl: HTMLInputElement | undefined = $state();
+
 	let zoomTimer: ReturnType<typeof setTimeout> | null = null;
 	let osdTimer: ReturnType<typeof setTimeout> | null = null;
 
@@ -1182,6 +1200,23 @@
 	const sortedSegments = $derived(sortSegments(transcript));
 	const sortedBookmarks = $derived(sortBookmarks(bookmarks));
 
+	// ── Transcript search deriveds (jatui-xmtnv) ─────────────────────────
+	/** Live only while the box is open with a non-empty query. */
+	const searchActive = $derived(searchOpen && searchQuery.trim().length > 0);
+	/** Matching rows in the pane's own play order — count and jump order
+	 *  agree with what's on screen. */
+	const searchMatches = $derived.by(() => {
+		if (!searchActive) return [];
+		const q = searchQuery.trim().toLowerCase();
+		return sortedSegments.filter((s) => s.text.toLowerCase().includes(q));
+	});
+	/** The match the Enter-cursor is on — wears the distinct "current" mark. */
+	const searchCurrentId = $derived(
+		searchMatchIdx >= 0 && searchMatchIdx < searchMatches.length
+			? searchMatches[searchMatchIdx].id
+			: null
+	);
+
 	/** Peaks normalised to 0–1 against their own max, so 0–1, 0–99 and 0–255 inputs all work. */
 	const peaks = $derived.by(() => {
 		const raw = waveform?.peaks;
@@ -2809,7 +2844,11 @@
 			return;
 		}
 		if (e.shiftKey) {
-			const delta = e.deltaY < 0 ? 5 : -5;
+			// Chrome on Linux/Windows and macOS turn Shift+wheel into a
+			// HORIZONTAL scroll, so deltaY is 0 and the value sits in deltaX.
+			// Use the effective delta to drive the seek step direction.
+			const d = e.deltaY !== 0 ? e.deltaY : e.deltaX;
+			const delta = d < 0 ? 5 : -5;
 			seekTo(currentTime + delta);
 			flashOsd(`${delta > 0 ? '+' : ''}${delta}s · ${formatTime(currentTime + delta, useHours)}`);
 			return;
@@ -2858,6 +2897,22 @@
 			return;
 		}
 
+		// The transcript search (jatui-xmtnv) owns Escape while it's open —
+		// even when focus has left its input — and re-focuses on `/`; every
+		// other key waits so typing never drives the player.
+		if (searchOpen) {
+			if (e.key === 'Escape') {
+				e.preventDefault();
+				e.stopPropagation();
+				closeSearch();
+			} else if (e.key === '/') {
+				e.preventDefault();
+				e.stopPropagation(); // the omnibar yields while focus is inside the player
+				searchInputEl?.focus();
+			}
+			return;
+		}
+
 		switch (e.key) {
 			case '?':
 				e.preventDefault();
@@ -2968,6 +3023,16 @@
 					flashOsd(transcriptVisible ? 'Transcript shown' : 'Transcript hidden');
 				}
 				return;
+			case '/':
+				// Transcript search (jatui-xmtnv). The omnibar yields: focus is
+				// inside the player, so this keydown never reaches the page's
+				// own `/` handler (stopPropagation below the player root).
+				if (sortedSegments.length > 0) {
+					e.preventDefault();
+					e.stopPropagation();
+					openSearch();
+				}
+				return;
 			case 'n':
 			case 'N':
 				if (night !== undefined) {
@@ -3106,6 +3171,88 @@
 		seekTo(seg.startSec);
 	}
 
+	// ── Transcript search (jatui-xmtnv) ───────────────────────────────────
+	/** `/`: open the box (showing the transcript if it was hidden) and hand
+	 *  it focus once it mounts — the effect below lands it. */
+	function openSearch() {
+		if (sortedSegments.length === 0) return;
+		transcriptVisible = true;
+		searchOpen = true;
+		searchMatchIdx = -1;
+	}
+	/** Esc / the × button: close, clear, and give the keys back to the map. */
+	function closeSearch() {
+		searchOpen = false;
+		searchQuery = '';
+		searchMatchIdx = -1;
+		rootEl?.focus();
+	}
+	/** Enter (next) / Shift+Enter (previous), wrapping. With no cursor yet a
+	 *  search opened mid-talk starts from the match at/after the playhead. */
+	function jumpSearch(direction: 1 | -1) {
+		const matches = searchMatches;
+		if (matches.length === 0) return;
+		searchMatchIdx = pickMatch(
+			matches.map((m) => m.startSec),
+			currentTime,
+			direction,
+			searchMatchIdx
+		);
+		seekTo(matches[searchMatchIdx].startSec);
+	}
+	/** The box owns its keys — never leak into the player map or the page
+	 *  omnibar while it's open (typing `k` must not pause, `/` must not
+	 *  re-open the omnibar). */
+	function onSearchKeydown(e: KeyboardEvent) {
+		e.stopPropagation();
+		if (e.key === 'Enter') {
+			e.preventDefault();
+			jumpSearch(e.shiftKey ? -1 : 1);
+		} else if (e.key === 'Escape') {
+			e.preventDefault();
+			closeSearch();
+		}
+	}
+	// Focus + select the box when it opens (the input mounts with it).
+	$effect(() => {
+		if (searchOpen && searchInputEl) {
+			searchInputEl.focus();
+			searchInputEl.select();
+		}
+	});
+
+	// ── Transcript wheel scrub (jatui-xmtnv) ─────────────────────────────────
+	// A plain wheel over the transcript pane scrolls it natively — exactly as
+	// before (the reader's own scroll, follow-intent logic untouched —
+	// jatui-ap4oz/ee2ty); preventDefault is NEVER taken for it, so the page is
+	// never trapped. Shift+wheel steps PLAYBACK one line at a time (extension
+	// library.js:8580 parity, matching Shift+wheel over the video = seek): the
+	// pure decision in video/transcriptSearch.ts accumulates deltas so one
+	// notch is one line — a mouse wheel's ~100px notches step exactly once
+	// each and a trackpad's stream of small deltas never flies through the
+	// transcript. Seeking makes the stepped line active, so the pane follows
+	// it (the follow's own scrolls are never intent).
+	let lineWheelAccum = 0;
+	function onTranscriptWheel(e: WheelEvent) {
+		const d = e.deltaY !== 0 ? e.deltaY : e.deltaX;
+		const decision = transcriptWheelDecision(
+			e.shiftKey,
+			sortedSegments.length > 0,
+			d,
+			lineWheelAccum
+		);
+		if (!decision.claimed) return; // plain wheel = native pane scroll
+		e.preventDefault();
+		lineWheelAccum = decision.nextAccum;
+		if (!decision.shouldStep) return;
+		const target = lineScrubTarget(
+			currentTime,
+			sortedSegments.map((s) => s.startSec),
+			decision.direction
+		);
+		if (target != null) seekTo(target);
+	}
+
 	// No active line (seeked past the transcript) ⇒ nothing to jump to.
 	$effect(() => {
 		if (!activeSegment && followPaused) untrack(() => (followPaused = false));
@@ -3795,10 +3942,42 @@
 			style:--vp-transcript-max={transcriptMaxHeight}
 			style:--vp-transcript-side-max={!transcriptMaxHeight && mainHeight > 0 ? `${mainHeight}px` : undefined}
 		>
+		{#if searchOpen}
+			<!-- Transcript search (jatui-xmtnv): `/` opened it. Enter jumps to
+			     the next match (Shift+Enter back), Esc closes; the count is
+			     aria-live so a screen reader hears match N of M. -->
+			<div class="vp-search">
+				<input
+					class="vp-search-input"
+					type="text"
+					placeholder="Search transcript"
+					aria-label="Search transcript"
+					spellcheck="false"
+					bind:value={searchQuery}
+					bind:this={searchInputEl}
+					oninput={() => (searchMatchIdx = -1)}
+					onkeydown={onSearchKeydown}
+				/>
+				<span class="vp-search-count" aria-live="polite">
+					{searchMatches.length === 0
+						? (searchActive ? 'No matches' : '')
+						: searchMatchIdx >= 0
+							? `${searchMatchIdx + 1} / ${searchMatches.length}`
+							: `${searchMatches.length}`}
+				</span>
+				<button
+					type="button"
+					class="vp-search-close"
+					aria-label="Close search"
+					onclick={closeSearch}
+				>×</button>
+			</div>
+		{/if}
 		<div
 			class="vp-transcript"
 			use:transcriptPaneAction
 			onscroll={onTranscriptScroll}
+			onwheel={onTranscriptWheel}
 		>
 			{#if transWindow}
 				<!-- Windowed: only the rows near the viewport exist in the DOM.
@@ -3823,7 +4002,15 @@
 								{seg.speakerName ?? 'Unknown speaker'}
 							</span>
 						{/if}
-						<span class="vp-row-text">{seg.text}</span>
+						<span class="vp-row-text">
+							{#if searchActive}
+								<!-- Search marks are safe HTML: highlightRowHtml escapes
+								     everything but its own <mark> tags (jatui-xmtnv). -->
+								{@html highlightRowHtml(seg.text, searchQuery, searchCurrentId === seg.id)}
+							{:else}
+								{seg.text}
+							{/if}
+						</span>
 					</button>
 				{/each}
 				<div class="vp-spacer" style="height: {transWindow.padBottom}px" aria-hidden="true"></div>
@@ -3846,7 +4033,13 @@
 								{seg.speakerName ?? 'Unknown speaker'}
 							</span>
 						{/if}
-						<span class="vp-row-text">{seg.text}</span>
+						<span class="vp-row-text">
+							{#if searchActive}
+								{@html highlightRowHtml(seg.text, searchQuery, searchCurrentId === seg.id)}
+							{:else}
+								{seg.text}
+							{/if}
+						</span>
 					</button>
 				{/each}
 			{/if}
@@ -4909,6 +5102,79 @@
 		}
 	}
 
+	/* Transcript search (jatui-xmtnv): a slim bar over the pane's top edge.
+	   Focus ring on the input only; marks tint with the primary token, and
+	   the cursor's match is filled so "which match am I on" is legible at a
+	   glance. */
+	.vp-search {
+		position: absolute;
+		top: 0;
+		left: 0;
+		right: 0;
+		z-index: 3;
+		display: flex;
+		align-items: center;
+		gap: var(--jatui-space-sm, 4px);
+		padding: var(--jatui-space-sm, 4px) var(--jatui-space-md, 6px);
+		background: var(--color-base-100);
+		border: var(--jatui-border-w, 1px) solid
+			color-mix(in oklch, var(--color-primary) 45%, transparent);
+		border-radius: var(--jatui-radius-box, 0.5rem);
+	}
+
+	.vp-search-input {
+		flex: 1 1 auto;
+		min-width: 0;
+		background: none;
+		border: none;
+		outline: none;
+		color: var(--color-base-content);
+		font-size: 0.8125rem;
+		padding: 0;
+	}
+
+	.vp-search-input::placeholder {
+		color: color-mix(in oklch, var(--color-base-content) 45%, transparent);
+	}
+
+	.vp-search-count {
+		flex: none;
+		font-family: ui-monospace, monospace;
+		font-size: 0.66rem;
+		color: color-mix(in oklch, var(--color-base-content) 55%, transparent);
+	}
+
+	.vp-search-close {
+		flex: none;
+		background: none;
+		border: none;
+		color: var(--color-base-content);
+		cursor: pointer;
+		padding: 0 var(--jatui-space-sm, 4px);
+		font-size: 0.9rem;
+		line-height: 1;
+		border-radius: var(--jatui-radius-field, 0.25rem);
+	}
+
+	.vp-search-close:hover {
+		background: color-mix(in oklch, var(--color-base-content) 8%, transparent);
+	}
+
+	/* Match highlight inside a transcript row — an <mark> tag, so UA styling
+	   is overridden with the token surface. The cursor's match is filled with
+	   the primary token; the rest is a softer tint. */
+	.vp-row-text :global(mark.vp-search-mark) {
+		background: color-mix(in oklch, var(--color-primary) 20%, transparent);
+		color: inherit;
+		border-radius: 2px;
+		padding: 0 1px;
+	}
+
+	.vp-row-text :global(mark.vp-search-mark.current) {
+		background: var(--color-primary);
+		color: var(--color-primary-content);
+	}
+
 	/* Keyboard help overlay — the `?` surface. Keycaps first, description after;
 	   token-only colours, same chrome family as the hover card. */
 	.vp-keys-backdrop {

package/dist/video/keys.d.ts

@@ -7,11 +7,11 @@
  * Space play/pause, ←/→ seek, ↑/↓ volume, M mute, −/= speed, Backspace reset
  * 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)
- * and `,` (settings) with the settings panel (mos-5lzns.35), each gated on
- * the host opting in.
+ * shortcuts, Home/End, and `/` transcript search (the pane has none yet).
+ * Deliberately NOT ported: F/M (favourite/file-under — library-app verbs,
+ * not player verbs). N (night cycle) landed with the night module
+ * (mos-5lzns.33) and `,` (settings) with the settings panel
+ * (mos-5lzns.35), each gated on the host opting in.
  */
 export interface PlayerKeyRow {
     /** Keycap label as shown in the help overlay — `/`-separated alternates. */

package/dist/video/keys.js

@@ -7,11 +7,11 @@
  * Space play/pause, ←/→ seek, ↑/↓ volume, M mute, −/= speed, Backspace reset
  * 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)
- * and `,` (settings) with the settings panel (mos-5lzns.35), each gated on
- * the host opting in.
+ * shortcuts, Home/End, and `/` transcript search (the pane has none yet).
+ * Deliberately NOT ported: F/M (favourite/file-under — library-app verbs,
+ * not player verbs). N (night cycle) landed with the night module
+ * (mos-5lzns.33) and `,` (settings) with the settings panel
+ * (mos-5lzns.35), each gated on the host opting in.
  */
 /** Order follows the help overlay: transport, seek, volume, speed, structure. */
 export const PLAYER_KEYS = [
@@ -34,6 +34,10 @@ export const PLAYER_KEYS = [
     // 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: '/', description: 'Search transcript', when: 'transcript' },
+    // Shift+wheel over the transcript pane steps PLAYBACK line by line —
+    // a plain wheel there scrolls the pane natively and is never claimed.
+    { keys: 'Shift+wheel', description: 'Over the transcript: steps line by line', 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/transcriptSearch.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Transcript search + wheel line-scrub (jatui-xmtnv — extension-library
+ * parity, mos-telti). Pure, DOM-free helpers the component calls; no module
+ * here reads settings or touches the <video> element (the advisor doctrine,
+ * src/lib/video/README.md).
+ *
+ * Two features:
+ *
+ * 1. `/` opens a search box over the transcript pane. Matches highlight in
+ *    place; Enter jumps to the next match (Shift+Enter the previous one,
+ *    wrapping); Esc closes. The page omnibar's own `/` yields while focus is
+ *    inside the player — the component stops the keydown's propagation when
+ *    it claims the key.
+ * 2. The wheel over the transcript pane steps PLAYBACK one line at a time —
+ *    not the pane's scroll. Deltas accumulate so one notch is one line: a
+ *    mouse wheel's ~100px notches step exactly once each, and a trackpad's
+ *    stream of small deltas never flies through the transcript.
+ */
+/** Wheel delta that equals one line step. A mouse notch is ~100–120; a
+ *  trackpad emits many small deltas — accumulating keeps one notch = one
+ *  line without making trackpad scrub feel stuck. */
+export declare const WHEEL_LINE_NOTCH = 50;
+/** Escaping for the {@html} path: transcript text is host data, never markup. */
+export declare function escapeHtml(text: string): string;
+/**
+ * Case-insensitive, non-overlapping `[start, end)` ranges of every occurrence
+ * of `query` in `text`. An empty (or whitespace-only) query matches nothing.
+ */
+export declare function searchHits(text: string, query: string): Array<{
+    start: number;
+    end: number;
+}>;
+/**
+ * HTML for one transcript row's text with `<mark>` around every match —
+ * safe to feed to `{@html}`: the surrounding text is escaped, only the mark
+ * tags are ours. `current` (the Enter-cursor's row) wears a second class so
+ * the player can style the match you're ON distinctly from the rest.
+ */
+export declare function highlightRowHtml(text: string, query: string, current: boolean): string;
+/**
+ * The segment to land on when the wheel steps playback one line. Wheel-down
+ * (direction 1) seeks to the NEXT line's start; wheel-up (−1) re-plays the
+ * line the playhead is already in when it is more than `grace` seconds past
+ * its start (one up-notch replays what you just heard), otherwise the
+ * previous line. Returns null at the transcript's edges.
+ */
+export declare function lineScrubTarget(currentTime: number, starts: ArrayLike<number>, direction: 1 | -1, grace?: number): number | null;
+/** What the transcript pane's wheel handler should do with one wheel event. */
+export interface TranscriptWheelDecision {
+    /** True when the wheel is the shift verb — the handler must preventDefault. */
+    claimed: boolean;
+    /** True when the accumulated delta crossed a notch: step a line now. */
+    shouldStep: boolean;
+    /** Step direction: 1 = next line (wheel down), −1 = previous (wheel up). */
+    direction: 1 | -1;
+    /** The accumulator to carry to the next wheel event. */
+    nextAccum: number;
+}
+/**
+ * Decide one transcript-pane wheel event. A plain wheel (no shift) or a
+ * pane with no transcript is NEVER claimed — native scroll, accumulator
+ * untouched. A shift wheel accumulates deltas; crossing {@link WHEEL_LINE_NOTCH}
+ * spends the accumulator (back to 0) and steps one line in the sign's
+ * direction.
+ */
+/**
+ * The effective wheel delta for a shift-modified gesture. Chrome on
+ * Linux/Windows and macOS turn Shift+wheel into a HORIZONTAL scroll:
+ * `e.deltaY` is 0 and the value sits in `e.deltaX`. Headless browsers don't
+ * swap, so tests only checking `deltaY` pass while a real browser never
+ * steps. Every shift verb must read this fallback.
+ */
+export declare function effectiveWheelDelta(deltaY: number, deltaX: number): number;
+export declare function transcriptWheelDecision(shiftKey: boolean, hasSegments: boolean, deltaY: number, accum: number): TranscriptWheelDecision;
+/** Which match Enter/Shift+Enter lands on. With no cursor yet, the first
+ *  match at/after the playhead (before it for backwards) — a search opened
+ *  mid-talk starts where you are, not at the top. Afterwards, the cursor
+ *  walks the match list and wraps at its ends. Returns the index, or −1 when
+ *  there are no matches. */
+export declare function pickMatch(matchStarts: ArrayLike<number>, currentTime: number, direction: 1 | -1, cursor: number): number;

package/dist/video/transcriptSearch.js

@@ -0,0 +1,153 @@
+/**
+ * Transcript search + wheel line-scrub (jatui-xmtnv — extension-library
+ * parity, mos-telti). Pure, DOM-free helpers the component calls; no module
+ * here reads settings or touches the <video> element (the advisor doctrine,
+ * src/lib/video/README.md).
+ *
+ * Two features:
+ *
+ * 1. `/` opens a search box over the transcript pane. Matches highlight in
+ *    place; Enter jumps to the next match (Shift+Enter the previous one,
+ *    wrapping); Esc closes. The page omnibar's own `/` yields while focus is
+ *    inside the player — the component stops the keydown's propagation when
+ *    it claims the key.
+ * 2. The wheel over the transcript pane steps PLAYBACK one line at a time —
+ *    not the pane's scroll. Deltas accumulate so one notch is one line: a
+ *    mouse wheel's ~100px notches step exactly once each, and a trackpad's
+ *    stream of small deltas never flies through the transcript.
+ */
+/** Wheel delta that equals one line step. A mouse notch is ~100–120; a
+ *  trackpad emits many small deltas — accumulating keeps one notch = one
+ *  line without making trackpad scrub feel stuck. */
+export const WHEEL_LINE_NOTCH = 50;
+/** Escaping for the {@html} path: transcript text is host data, never markup. */
+export function escapeHtml(text) {
+    return text
+        .replaceAll('&', '&amp;')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;')
+        .replaceAll('"', '&quot;')
+        .replaceAll("'", '&#39;');
+}
+/**
+ * Case-insensitive, non-overlapping `[start, end)` ranges of every occurrence
+ * of `query` in `text`. An empty (or whitespace-only) query matches nothing.
+ */
+export function searchHits(text, query) {
+    const q = query.trim().toLowerCase();
+    if (!q)
+        return [];
+    const lower = text.toLowerCase();
+    const hits = [];
+    let from = 0;
+    for (;;) {
+        const at = lower.indexOf(q, from);
+        if (at < 0)
+            break;
+        hits.push({ start: at, end: at + q.length });
+        from = at + q.length;
+    }
+    return hits;
+}
+/**
+ * HTML for one transcript row's text with `<mark>` around every match —
+ * safe to feed to `{@html}`: the surrounding text is escaped, only the mark
+ * tags are ours. `current` (the Enter-cursor's row) wears a second class so
+ * the player can style the match you're ON distinctly from the rest.
+ */
+export function highlightRowHtml(text, query, current) {
+    const hits = searchHits(text, query);
+    if (hits.length === 0)
+        return escapeHtml(text);
+    const cls = current ? 'vp-search-mark current' : 'vp-search-mark';
+    let out = '';
+    let at = 0;
+    for (const hit of hits) {
+        out += escapeHtml(text.slice(at, hit.start));
+        out += `<mark class="${cls}">${escapeHtml(text.slice(hit.start, hit.end))}</mark>`;
+        at = hit.end;
+    }
+    out += escapeHtml(text.slice(at));
+    return out;
+}
+/**
+ * The segment to land on when the wheel steps playback one line. Wheel-down
+ * (direction 1) seeks to the NEXT line's start; wheel-up (−1) re-plays the
+ * line the playhead is already in when it is more than `grace` seconds past
+ * its start (one up-notch replays what you just heard), otherwise the
+ * previous line. Returns null at the transcript's edges.
+ */
+export function lineScrubTarget(currentTime, starts, direction, grace = 0.5) {
+    const n = starts.length;
+    if (n === 0)
+        return null;
+    // Index of the line the playhead is in (the last start ≤ time).
+    let idx = 0;
+    for (let i = 0; i < n; i++) {
+        if (starts[i] <= currentTime)
+            idx = i;
+        else
+            break;
+    }
+    if (direction === 1) {
+        return idx + 1 < n ? starts[idx + 1] : null;
+    }
+    if (currentTime - starts[idx] > grace)
+        return starts[idx];
+    return idx > 0 ? starts[idx - 1] : null;
+}
+/**
+ * Decide one transcript-pane wheel event. A plain wheel (no shift) or a
+ * pane with no transcript is NEVER claimed — native scroll, accumulator
+ * untouched. A shift wheel accumulates deltas; crossing {@link WHEEL_LINE_NOTCH}
+ * spends the accumulator (back to 0) and steps one line in the sign's
+ * direction.
+ */
+// ── transcriptWheelDecision ───────────────────────────────────────────────
+/**
+ * The effective wheel delta for a shift-modified gesture. Chrome on
+ * Linux/Windows and macOS turn Shift+wheel into a HORIZONTAL scroll:
+ * `e.deltaY` is 0 and the value sits in `e.deltaX`. Headless browsers don't
+ * swap, so tests only checking `deltaY` pass while a real browser never
+ * steps. Every shift verb must read this fallback.
+ */
+export function effectiveWheelDelta(deltaY, deltaX) {
+    return deltaY !== 0 ? deltaY : deltaX;
+}
+export function transcriptWheelDecision(shiftKey, hasSegments, deltaY, accum) {
+    if (!shiftKey || !hasSegments) {
+        return { claimed: false, shouldStep: false, direction: 1, nextAccum: accum };
+    }
+    const next = accum + deltaY;
+    if (Math.abs(next) < WHEEL_LINE_NOTCH) {
+        return { claimed: true, shouldStep: false, direction: next > 0 ? 1 : -1, nextAccum: next };
+    }
+    return { claimed: true, shouldStep: true, direction: next > 0 ? 1 : -1, nextAccum: 0 };
+}
+/** Which match Enter/Shift+Enter lands on. With no cursor yet, the first
+ *  match at/after the playhead (before it for backwards) — a search opened
+ *  mid-talk starts where you are, not at the top. Afterwards, the cursor
+ *  walks the match list and wraps at its ends. Returns the index, or −1 when
+ *  there are no matches. */
+export function pickMatch(matchStarts, currentTime, direction, cursor) {
+    const n = matchStarts.length;
+    if (n === 0)
+        return -1;
+    if (cursor < 0 || cursor >= n) {
+        if (direction === 1) {
+            for (let i = 0; i < n; i++)
+                if (matchStarts[i] >= currentTime)
+                    return i;
+            return 0;
+        }
+        let idx = 0;
+        for (let i = 0; i < n; i++) {
+            if (matchStarts[i] <= currentTime)
+                idx = i;
+            else
+                break;
+        }
+        return idx;
+    }
+    return (cursor + direction + n) % n;
+}

package/package.json

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