@joewinke/jatui 0.31.1 → 0.32.0

package/dist/components/VideoPlayer.svelte

@@ -9,6 +9,8 @@
 		VideoWaveform,
 		VideoSpeakerTalkTime
 	} from '../video/types';
+	// mos-777hj — chapter rail public types.
+	export type { RailChapter, RailChapterStatus } from '../video/chapterRail';
 	// mos-5lzns.30 — one-axis state, the light track, social markers.
 	export type { BandAxis, BandState } from '../video/band/axis';
 	export type { VideoLumaTrack } from '../video/band/luma';
@@ -79,8 +81,11 @@
 	 * colour, cycled per speaker — not brand colour).
 	 */
 
-	import { onMount, untrack } from 'svelte';
+	import { onMount, untrack, type Snippet } from 'svelte';
 	import { getDaisyUIColor, watchThemeChanges, clearColorCache } from '../utils/daisyuiColors';
+	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 type {
 		VideoBookmark,
 		VideoChapter,
@@ -255,6 +260,9 @@
 		captionsLang = 'en',
 		captionsDefault = true,
 		chapters = [],
+		chapterRail: chapterRailProp = 'off',
+		onChapterSelect = undefined,
+		belowStage = undefined,
 		speakers = [],
 		transcript = [],
 		bookmarks = [],
@@ -369,6 +377,33 @@
 		 */
 		captionsDefault?: boolean;
 		chapters?: VideoChapter[];
+		/**
+		 * mos-777hj — the live chapter rail. `'side'` (with chapters present)
+		 * renders a sticky chapter pane beside the main column at ≥64rem — one
+		 * row per chapter with time, title, status dot and summary, the active
+		 * row tracking the playhead (aria-current, auto-scroll), a progress
+		 * fill inside the active row and a played check behind the playhead —
+		 * and a horizontal chip strip under the player below 64rem. Rows seek
+		 * to the chapter and play; the active row carries the replay affordance
+		 * (clicking it again replays from its start). Keyboard: listNav j/k to
+		 * move, Enter to play, while the rail holds focus. Default `'off'` —
+		 * the rail is opt-in and leaves the player exactly as it was.
+		 */
+		chapterRail?: 'side' | 'off';
+		/**
+		 * Fires when the viewer picks a chapter (row click / Enter / replay):
+		 * the host pins its own view (e.g. a per-chapter visual panel) — the
+		 * rail itself always keeps time-tracking the playhead.
+		 */
+		onChapterSelect?: (chapter: VideoChapter, index: number) => void;
+		/**
+		 * Optional snippet rendered between the stage and the transcript — the
+		 * host's own content in the player's main column (e.g. a "now
+		 * discussing" panel bound to the active chapter). Designed for
+		 * `transcriptPosition: 'below'`; beside a side transcript it renders
+		 * under the stage in the stage's column.
+		 */
+		belowStage?: Snippet;
 		speakers?: VideoSpeakerTurn[];
 		transcript?: VideoTranscriptSegment[];
 		bookmarks?: VideoBookmark[];
@@ -960,6 +995,42 @@
 	const useHours = $derived(effectiveDuration >= 3600);
 
 	const sortedChapters = $derived(sortChapters(chapters));
+
+	// ── Chapter rail (mos-777hj) ─────────────────────────────────────────
+	/** The rail pane exists only when opted in AND there is something to rail. */
+	const railOn = $derived(chapterRailProp === 'side' && sortedChapters.length > 0);
+	/** Rows recomputed per playhead tick — ends, played checks, progress fill. */
+	const railRows = $derived(railOn ? railChapters(sortedChapters, effectiveDuration, currentTime) : []);
+	const railActive = $derived(railOn ? activeRailIndex(sortedChapters, currentTime) : -1);
+	let chapterRailEl: HTMLElement | null = $state(null);
+
+	/** Row click / Enter / replay: seek to the chapter and play it. */
+	function chapterGo(index: number) {
+		const ch = sortedChapters[index];
+		if (!ch) return;
+		seekTo(ch.startSec);
+		videoEl?.play()?.catch(() => {});
+		onChapterSelect?.(ch, index);
+	}
+
+	/** listNav onSelect — the element carries its row index. */
+	function onRailSelect(el: HTMLElement) {
+		const idx = Number(el.dataset.chapterIndex);
+		if (Number.isInteger(idx)) chapterGo(idx);
+	}
+
+	/** Keep the active row visible while playback tracks chapters. Nearest
+	 * only ever scrolls the rail's own overflow (never the page); smooth is
+	 * dropped under prefers-reduced-motion. */
+	$effect(() => {
+		if (!railOn || railActive < 0) return;
+		const row = chapterRailEl?.querySelector<HTMLElement>('.vp-chapter-row.active');
+		if (!row) return;
+		row.scrollIntoView({
+			block: 'nearest',
+			behavior: reduceMotion ? 'auto' : 'smooth'
+		});
+	});
 	const sortedTurns = $derived(sortTurns(speakers));
 	const sortedSegments = $derived(sortSegments(transcript));
 	const sortedBookmarks = $derived(sortBookmarks(bookmarks));
@@ -1094,6 +1165,16 @@
 		return { ...currentBandState };
 	}
 
+	/**
+	 * Callable on the instance (`bind:this`) — seek to an absolute second.
+	 * The host-side half of deep links (mos-777hj): a host that resolves its
+	 * own anchors (e.g. #chapter-<id>) seeks through this after mount, the
+	 * same place `startAt`/`?t=` seed from.
+	 */
+	export function seekToTime(sec: number) {
+		seekTo(sec);
+	}
+
 	const reportBand = createBandReporter(() => onBandChange);
 	$effect(() => {
 		const st = currentBandState;
@@ -1105,6 +1186,7 @@
 		PLAYER_KEYS.filter((row) => {
 			if (!row.when) return true;
 			if (row.when === 'chapters') return sortedChapters.length > 0;
+		if (row.when === 'rail') return railOn;
 			if (row.when === 'bookmarks') return onAddBookmark != null;
 			if (row.when === 'transcript') return sortedSegments.length > 0;
 			if (row.when === 'comments') return socialMarkers.comments.length > 0;
@@ -2532,6 +2614,10 @@
 		const target = e.target as HTMLElement | null;
 		const tag = target?.tagName;
 		if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT' || target?.isContentEditable) return;
+		// mos-777hj — the chapter rail owns j/k (listNav) and Enter/Space (row
+		// activation) while focus is inside it; without this guard a rail `k`
+		// would also toggle play/pause and a rail `j` also seek ±5s.
+		if (chapterRailEl && target && chapterRailEl.contains(target)) return;
 		if (e.metaKey || e.ctrlKey || e.altKey) return;
 		const v = videoEl;
 		if (!v) return;
@@ -2786,6 +2872,7 @@
 	class="vp-root {className}"
 	bind:this={rootEl}
 	class:vp-side={transcriptPosition === 'side' && sortedSegments.length > 0 && transcriptVisible}
+	class:vp-rail-side={railOn}
 	class:vp-one-axis={nativeBarHidden}
 	class:vp-night-capable={nightPresent}
 	class:vp-night-surround={surroundMix > 0.001}
@@ -3144,6 +3231,79 @@
 		{/if}
 	</div>
 
+	{#if railOn}
+		<!-- mos-777hj — the live chapter rail: one row per chapter with time,
+		     title, status dot and summary. The active row tracks the playhead
+		     (aria-current + auto-scroll), fills its thin progress bar, and
+		     carries the replay affordance; played chapters wear a check. A row
+		     click seeks there and plays (clicking the active row again replays
+		     it from its start). listNav owns j/k + Enter while the rail holds
+		     focus (global:false scopes the listener to this pane; the root
+		     keydown handler skips events from inside it). ≥64rem the pane is a
+		     sticky column; below it collapses to a horizontal chip strip. -->
+		<nav
+			class="vp-chapters"
+			bind:this={chapterRailEl}
+			aria-label="Chapters"
+			use:listNav={{
+				itemSelector: '.vp-chapter-row',
+				onSelect: onRailSelect,
+				focusedClass: 'jk-focused',
+				global: false
+			}}
+		>
+			{#each railRows as ch, i (i)}
+				<button
+					type="button"
+					class="vp-chapter-row"
+					class:active={railActive === i}
+					class:done={ch.played}
+					data-chapter-index={i}
+					aria-current={railActive === i ? 'true' : undefined}
+					onclick={() => chapterGo(i)}
+				>
+					<span class="vp-chapter-head">
+						{#if ch.status}
+							<span class="vp-chapter-dot vp-chapter-dot-{ch.status}" aria-hidden="true"></span>
+						{/if}
+						<span class="vp-chapter-time">{formatTime(ch.startSec, useHours)}</span>
+						<span class="vp-chapter-title">{ch.title}</span>
+						{#if ch.played}
+							<svg class="vp-chapter-check" viewBox="0 0 16 16" width="11" height="11" aria-hidden="true">
+								<path d="M2.5 8.5 6 12l7.5-8" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" />
+							</svg>
+						{/if}
+						{#if railActive === i}
+							<!-- Replay affordance: the active row's click already replays
+							     from its start, so the icon is the affordance's label. -->
+							<svg class="vp-chapter-replay" viewBox="0 0 24 24" width="12" height="12" aria-hidden="true">
+								<path d="M3 12a9 9 0 1 0 2.64-6.36M3 4v4h4" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" />
+							</svg>
+						{/if}
+					</span>
+					{#if ch.summary}
+						<span class="vp-chapter-summary">{ch.summary}</span>
+					{/if}
+					{#if railActive === i}
+						<span
+							class="vp-chapter-bar"
+							aria-hidden="true"
+							style="--vp-chapter-progress: {ch.progress}"
+						>
+							<span class="vp-chapter-fill"></span>
+						</span>
+					{/if}
+				</button>
+			{/each}
+		</nav>
+	{/if}
+
+	{#if belowStage}
+		<!-- mos-777hj — the host's content in the main column: under the stage
+		     (and its band), above the transcript. -->
+		<div class="vp-below-stage">{@render belowStage()}</div>
+	{/if}
+
 	{#if sortedSegments.length > 0 && transcriptVisible}
 		<div
 			class="vp-transcript"
@@ -3276,6 +3436,232 @@
 		}
 	}
 
+	/* ── Chapter rail (mos-777hj) ────────────────────────────────────────
+	   Opt-in (`chapterRail="side"` + chapters). ≥64rem the pane is a sticky
+	   column on the right of the main content (below the stage when the
+	   transcript sits below, a third column beside a side transcript);
+	   below 64rem the same DOM flows as a horizontal chip strip between the
+	   player and the below-stage content — grid areas re-place the panes,
+	   the DOM order never changes. Token-only chrome, dot tones resolve
+	   DaisyUI semantic vars. */
+	.vp-below-stage {
+		min-width: 0;
+	}
+
+	.vp-chapters {
+		display: flex;
+		flex-direction: column;
+		gap: 1px;
+		min-width: 0;
+		background: var(--color-base-100);
+		border: var(--jatui-border-w, 1px) solid
+			color-mix(in oklch, var(--color-base-content) 12%, transparent);
+		border-radius: var(--jatui-radius-box, 0.5rem);
+		padding: var(--jatui-space-sm, 4px);
+		overflow-y: auto;
+	}
+
+	.vp-chapter-row {
+		position: relative;
+		display: flex;
+		flex-direction: column;
+		gap: 2px;
+		background: none;
+		border: none;
+		border-radius: var(--jatui-radius-field, 0.25rem);
+		padding: var(--jatui-space-sm, 4px) var(--jatui-space-md, 6px);
+		text-align: left;
+		cursor: pointer;
+		transition: background var(--motion-fast, 150ms) var(--motion-glide, ease-out);
+	}
+
+	.vp-chapter-row:hover {
+		background: color-mix(in oklch, var(--color-base-content) 8%, transparent);
+	}
+
+	.vp-chapter-row.active {
+		background: color-mix(in oklch, var(--color-primary) 14%, transparent);
+		box-shadow: inset 2px 0 0 var(--color-primary);
+	}
+
+	/* listNav's cursor (j/k) — same family as the hover/active surfaces. */
+	.vp-chapter-row.jk-focused {
+		outline: 2px solid color-mix(in oklch, var(--color-primary) 55%, transparent);
+		outline-offset: -2px;
+	}
+
+	.vp-chapter-row.done .vp-chapter-title {
+		color: color-mix(in oklch, var(--color-base-content) 55%, transparent);
+	}
+
+	.vp-chapter-head {
+		display: flex;
+		align-items: baseline;
+		gap: var(--jatui-space-sm, 4px);
+		min-width: 0;
+	}
+
+	.vp-chapter-dot {
+		width: 0.5em;
+		height: 0.5em;
+		border-radius: var(--jatui-radius-selector, 0.375rem);
+		flex: none;
+		align-self: center;
+		background: var(--color-base-content);
+		opacity: 0.4;
+	}
+
+	.vp-chapter-dot-info {
+		background: var(--color-info);
+		opacity: 1;
+	}
+
+	.vp-chapter-dot-success {
+		background: var(--color-success);
+		opacity: 1;
+	}
+
+	.vp-chapter-dot-warning {
+		background: var(--color-warning);
+		opacity: 1;
+	}
+
+	.vp-chapter-dot-error {
+		background: var(--color-error);
+		opacity: 1;
+	}
+
+	.vp-chapter-time {
+		font-family: ui-monospace, monospace;
+		font-size: 0.66rem;
+		color: color-mix(in oklch, var(--color-base-content) 50%, transparent);
+		flex-shrink: 0;
+	}
+
+	.vp-chapter-title {
+		font-size: 0.76rem;
+		font-weight: 600;
+		color: var(--color-base-content);
+		flex: 1;
+		min-width: 0;
+		overflow: hidden;
+		text-overflow: ellipsis;
+		white-space: nowrap;
+	}
+
+	.vp-chapter-check {
+		color: var(--color-success);
+		flex: none;
+		align-self: center;
+	}
+
+	.vp-chapter-replay {
+		color: color-mix(in oklch, var(--color-primary) 80%, transparent);
+		flex: none;
+		align-self: center;
+	}
+
+	.vp-chapter-summary {
+		font-size: 0.68rem;
+		line-height: 1.35;
+		color: color-mix(in oklch, var(--color-base-content) 60%, transparent);
+		overflow: hidden;
+		display: -webkit-box;
+		-webkit-box-orient: vertical;
+		-webkit-line-clamp: 2;
+	}
+
+	/* The active row's thin fill: transform, not width — a compositor move
+	   that never relayouts the row, stepping with the playhead tick. */
+	.vp-chapter-bar {
+		position: absolute;
+		left: var(--jatui-space-md, 6px);
+		right: var(--jatui-space-md, 6px);
+		bottom: 1px;
+		height: 2px;
+		border-radius: 999px;
+		background: color-mix(in oklch, var(--color-base-content) 10%, transparent);
+		overflow: hidden;
+		pointer-events: none;
+	}
+
+	.vp-chapter-fill {
+		display: block;
+		width: 100%;
+		height: 100%;
+		border-radius: inherit;
+		background: var(--color-primary);
+		transform: scaleX(var(--vp-chapter-progress, 0));
+		transform-origin: left center;
+		transition: transform 120ms linear;
+	}
+
+	@media (max-width: 63.999rem) {
+		/* The chip strip: same rows, laid horizontally under the player. */
+		.vp-chapters {
+			flex-direction: row;
+			gap: var(--jatui-space-xs, 2px);
+			overflow-x: auto;
+			overflow-y: hidden;
+			padding: var(--jatui-space-xs, 2px);
+		}
+
+		.vp-chapter-row {
+			flex: none;
+			max-width: 16rem;
+			padding: var(--jatui-space-xs, 2px) var(--jatui-space-sm, 4px);
+		}
+
+		.vp-chapter-summary,
+		.vp-chapter-bar {
+			display: none;
+		}
+
+		.vp-chapter-title {
+			max-width: 12rem;
+		}
+	}
+
+	@media (min-width: 64rem) {
+		.vp-root.vp-rail-side {
+			display: grid;
+			grid-template-columns: minmax(0, 1fr) minmax(13rem, 16rem);
+			grid-template-areas:
+				'main rail'
+				'below rail'
+				'transcript rail';
+			gap: var(--jatui-space-lg, 12px);
+			align-items: start;
+		}
+
+		.vp-root.vp-rail-side > .vp-main {
+			grid-area: main;
+		}
+
+		.vp-root.vp-rail-side > .vp-chapters {
+			grid-area: rail;
+			position: sticky;
+			top: var(--jatui-space-lg, 12px);
+			max-height: calc(100vh - 2 * var(--jatui-space-lg, 12px));
+		}
+
+		.vp-root.vp-rail-side > .vp-below-stage {
+			grid-area: below;
+		}
+
+		.vp-root.vp-rail-side > .vp-transcript {
+			grid-area: transcript;
+		}
+
+		/* Rail beside a side transcript (theater): three columns. */
+		.vp-root.vp-side.vp-rail-side {
+			grid-template-columns: minmax(0, 3fr) minmax(16rem, 2fr) minmax(11rem, 14rem);
+			grid-template-areas:
+				'main transcript rail'
+				'below transcript rail';
+		}
+	}
+
 	.vp-stage {
 		position: relative;
 	}
@@ -3838,7 +4224,9 @@
 		.vp-lane-span,
 		.vp-chip,
 		.vp-add-btn,
-		.vp-row {
+		.vp-row,
+		.vp-chapter-row,
+		.vp-chapter-fill {
 			transition: none;
 		}
 	}

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

@@ -1,4 +1,5 @@
 export type { VideoChapter, VideoSpeakerTurn, VideoTranscriptSegment, VideoBookmark, VideoWaveform, VideoSpeakerTalkTime } from '../video/types';
+export type { RailChapter, RailChapterStatus } from '../video/chapterRail';
 export type { BandAxis, BandState } from '../video/band/axis';
 export type { VideoLumaTrack } from '../video/band/luma';
 export type { VideoMarker } from '../video/band/markers';
@@ -8,6 +9,58 @@ export type { VideoAdSpan, RateReport } from '../video/rate';
 export type { WindDownState, WindDownPhase, PresenceSource, VideoResumeStore, FlipSource } from '../video/presence';
 export type { ResumePoint } from '../video/advisors/resume-point';
 export type { VideoSettingsStore, SettingValue, SettingSpec } from '../video/settings';
+/**
+     * VideoPlayer — one video surface for everything, from a bare mp4 to a
+     * fully-analysed recording.
+     *
+     * Marries two prior implementations rather than inventing a third:
+     *
+     *  1. extension-library's framework-agnostic `mountPlayer` (player.js) —
+     *     the timeline band: waveform envelope as the scrubber, chapters as
+     *     structure inside it, diarized speaker colouring, bookmark diamonds,
+     *     scroll-to-zoom, hover card with "what's being said here".
+     *  2. jatui's TranscriptPlayer — the transcript pane: click a line to seek,
+     *     active line auto-scroll, solo-speaker playback, talk-time bars.
+     *
+     * EVERY intelligence prop is optional. A bare `<VideoPlayer {src} />` still
+     * gets the band (a real scrubber with hover-time, click-to-seek, keyboard
+     * seek), wheel volume and the keyboard map; chapters, speakers, waveform,
+     * transcript, bookmarks and talk-time each light up their own pane as the
+     * data exists. Nothing shifts layout when data arrives late (diarization is
+     * slow) — the band's slots are reserved from the first frame.
+     *
+     * ── Design notes carried over from player.js ────────────────────────────
+     * · ONE time axis. Every position — waveform bars, chapter flags, bookmarks,
+     *   the speaker lane, click/hover-to-seek — maps through the band window's
+     *   secToFrac/fracToSec (video/band.ts), so scroll-to-zoom is one piece of
+     *   state everything else respects for free.
+     * · ONE speaker surface. With a waveform, the envelope's own bars wear the
+     *   turn colours; the slim lane under it paints only as the no-waveform
+     *   fallback. Never two stacked time-parallel strips.
+     * · Chapter flags sit on the TOP edge, bookmark diamonds on the BOTTOM edge —
+     *   same idea (a marker on the timeline), different origin (the model's vs.
+     *   yours), so the two families are never confused at a glance.
+     * · The wheel means different things in different regions, and each region is
+     *   its own hover target so nothing is ambiguous: over the video it's volume
+     *   (shift = seek, alt = speed); over the band it's zoom.
+     * · The keyboard map (video/keys.ts) is the single source the keydown
+     *   handler and the `?` overlay both read — a key that exists is documented,
+     *   a documented key exists.
+     *
+     * Internals live in `src/lib/video/` (band / keys / rate / deepLink /
+     * settings + types/time/model; audio, night and presence are contracts for
+     * mos-5lzns.31/.33/.34 — see that directory's README for the ownership map
+     * and the advisor doctrine).
+     *
+     * Deliberately NOT ported: player.js's trim region (in/out handles). That's
+     * clip-editing, not playback, and belongs in an editor component.
+     *
+     * Theming is token-only — DaisyUI semantic vars for chrome, resolved at
+     * runtime via `getDaisyUIColor` for the canvas, repainted on theme change.
+     * Speaker hues follow TranscriptPlayer's oklch palette (data-driven identity
+     * colour, cycled per speaker — not brand colour).
+     */
+import { type Snippet } from 'svelte';
 import type { VideoBookmark, VideoChapter, VideoSpeakerTalkTime, VideoSpeakerTurn, VideoTranscriptSegment, VideoWaveform } from '../video/types';
 import { type BandState } from '../video/band/axis';
 import { type VideoLumaTrack } from '../video/band/luma';
@@ -58,6 +111,33 @@ type $$ComponentProps = {
      */
     captionsDefault?: boolean;
     chapters?: VideoChapter[];
+    /**
+     * mos-777hj — the live chapter rail. `'side'` (with chapters present)
+     * renders a sticky chapter pane beside the main column at ≥64rem — one
+     * row per chapter with time, title, status dot and summary, the active
+     * row tracking the playhead (aria-current, auto-scroll), a progress
+     * fill inside the active row and a played check behind the playhead —
+     * and a horizontal chip strip under the player below 64rem. Rows seek
+     * to the chapter and play; the active row carries the replay affordance
+     * (clicking it again replays from its start). Keyboard: listNav j/k to
+     * move, Enter to play, while the rail holds focus. Default `'off'` —
+     * the rail is opt-in and leaves the player exactly as it was.
+     */
+    chapterRail?: 'side' | 'off';
+    /**
+     * Fires when the viewer picks a chapter (row click / Enter / replay):
+     * the host pins its own view (e.g. a per-chapter visual panel) — the
+     * rail itself always keeps time-tracking the playhead.
+     */
+    onChapterSelect?: (chapter: VideoChapter, index: number) => void;
+    /**
+     * Optional snippet rendered between the stage and the transcript — the
+     * host's own content in the player's main column (e.g. a "now
+     * discussing" panel bound to the active chapter). Designed for
+     * `transcriptPosition: 'below'`; beside a side transcript it renders
+     * under the stage in the stage's column.
+     */
+    belowStage?: Snippet;
     speakers?: VideoSpeakerTurn[];
     transcript?: VideoTranscriptSegment[];
     bookmarks?: VideoBookmark[];
@@ -321,6 +401,7 @@ type $$ComponentProps = {
 };
 declare const VideoPlayer: import("svelte").Component<$$ComponentProps, {
     bandState: () => BandState;
+    seekToTime: (sec: number) => void;
 }, "night" | "nightDepth">;
 type VideoPlayer = ReturnType<typeof VideoPlayer>;
 export default VideoPlayer;

package/dist/sound/SoundSettings.svelte

@@ -71,7 +71,7 @@
 		const p = player ?? getSoundPlayer();
 		// A preview click is a real gesture: unlock here too, so a first-ever
 		// preview on iOS actually sounds instead of resuming a dead context.
-		void p.unlock();
+		void p.unlock?.();
 		previewing = p.play(name, { preview: true, loop: false });
 		previewTimer = setTimeout(stopPreview, PREVIEW_MAX_MS);
 	}

package/dist/sound/player.d.ts

@@ -53,15 +53,17 @@ export interface SoundPlayer {
     /**
      * Unlock audio output from inside a user-gesture handler (iOS/Safari
      * keeps a context suspended unless the gesture created/resumed it —
-     * see `sound/unlock.ts`). Backends without an unlock concept resolve
-     * immediately. A cheap no-op once unlocked.
+     * see `sound/unlock.ts`). OPTIONAL: a custom player without one is
+     * assumed fine — unlock resolves and `unlocked` reads undefined, which
+     * hosts treat as "no unlock concept". A cheap no-op once unlocked.
      */
-    unlock(): Promise<void>;
+    unlock?(): Promise<void>;
     /**
-     * True when the backend reports a running output context; a backend
-     * with no unlock concept always reports true. False before any unlock.
+     * True when the player's backend reports a running output context;
+     * false before any unlock, undefined when the player has no unlock
+     * concept.
      */
-    readonly unlocked: boolean;
+    readonly unlocked?: boolean;
     /** Decode clips ahead of time (defaults to every semantic name). */
     preload(names?: readonly SoundId[]): Promise<void>;
     stopAll(): void;

package/dist/sound/unlock.js

@@ -30,7 +30,7 @@ import { getSoundPlayer } from './player';
  * is a cheap no-op once the context is running.
  */
 export async function unlockSound() {
-    await getSoundPlayer().unlock();
+    await getSoundPlayer().unlock?.();
 }
 const GESTURES = ['pointerup', 'touchend', 'click', 'keydown'];
 /** The target `armSoundUnlock` installed its one-shot listener on, if any. */

package/dist/video/README.md

@@ -11,7 +11,8 @@ props + callback surfaces.
 
 | File | Owner | Contents |
 |------|-------|----------|
-| `types.ts` | .28 (done) | The public data contracts — `VideoChapter`, `VideoSpeakerTurn`, `VideoTranscriptSegment`, `VideoBookmark`, `VideoWaveform`, `VideoSpeakerTalkTime`. Re-exported by the component, so `import type … from 'jatui'` is unchanged. |
+| `types.ts` | .28 (done) | The public data contracts — `VideoChapter`, `VideoSpeakerTurn`, `VideoTranscriptSegment`, `VideoBookmark`, `VideoWaveform`, `VideoSpeakerTalkTime`. Re-exported by the component, so `import type … from 'jatui'` is unchanged. .777hj adds `VideoChapter.endSec/summary/status` (all optional — the band ignores them). |
+| `chapterRail.ts` | **mos-777hj** | The opt-in `chapterRail: 'side'` pane's pure state: `railChapters(chapters, duration, t)` derives row ends (explicit `endSec` → next start → duration), the played check and the 0–1 progress fill for the row containing `t`; `activeRailIndex` is the row-highlight index. The component owns the DOM: sticky right column ≥64rem (chip strip below), rows seek+play on click, replay affordance on the active row, listNav j/k+Enter (the root keydown handler skips events from inside the rail), `onChapterSelect` for host-side pinning, `belowStage` snippet slot between stage and transcript, `seekToTime()` instance export for host deep links. |
 | `time.ts` | .28 (done) | Pure formatting: `formatTime`, `formatDuration`, `truncate`, `aspectRatioCss`. |
 | `model.ts` | .28 (done) | Speaker registry + identity colours + talk-time derivation + the sort normalisations. `ALL_KEY`/`UNKNOWN_KEY` live here. |
 | `band.ts` | .28 (done) — extended by **.30** | The timeline band: zoom window (`BandWindow`, `zoomAt`, `followPlayhead`), hit tests (`segmentAt`, `chapterAt`, `biasToSegmentStart`, `nearestBookmark`), and `paintBand` (canvas). .30 adds one-axis arbitration + the light ribbon; its state lives HERE. |

package/dist/video/chapterRail.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Chapter rail state (mos-777hj) — the pure half of VideoPlayer's opt-in
+ * `chapterRail: 'side'` pane: one row per chapter (title, time, status dot,
+ * summary), the active row tracking the playhead, a progress fill inside the
+ * active row and a played check once the playhead moves past a chapter's end.
+ *
+ * The component owns the DOM (rows, click-to-seek-and-play, listNav, sticky
+ * column, small-screen chip strip); everything derivable from
+ * (chapters, duration, playhead) lives HERE so it is node-testable under
+ * `npm run test:unit` — same discipline as band.ts / transcriptWindow.ts.
+ *
+ * Chapter ends: a chapter without an explicit `endSec` runs to the NEXT
+ * chapter's start; the last one runs to the media duration when known. With
+ * no duration and no following chapter the chapter is open-ended — its row
+ * simply never shows a played check or progress (division guards to 0).
+ */
+import type { VideoChapter } from './types';
+/** Dot tones, resolved to DaisyUI semantic vars by the component's CSS. */
+export type RailChapterStatus = 'info' | 'success' | 'warning' | 'error';
+/** A chapter as the rail renders it: end derived when absent. */
+export interface RailChapter {
+    startSec: number;
+    endSec: number;
+    title: string;
+    summary: string | null;
+    status: RailChapterStatus | null;
+    /** True once the playhead has moved past this chapter's end. */
+    played: boolean;
+    /** 0..1 fill for the row containing `t`; exactly 0 for every other row. */
+    progress: number;
+}
+/**
+ * The rail's rows for one playhead instant. `chapters` must be sorted by
+ * startSec (the component passes its `sortedChapters`); entries with a
+ * non-finite start are dropped, mirroring sortChapters' own filter.
+ *
+ * `t` before the first chapter (or exactly on it) marks that first chapter
+ * active with progress from its own start; there is no "before the program"
+ * row — the program starts at its first chapter.
+ */
+export declare function railChapters(chapters: VideoChapter[], durationSec: number | null, t: number): RailChapter[];
+/**
+ * Index of the row containing `t` (the LAST chapter whose startSec <= t), or
+ * -1 when `t` sits before every chapter / the list is empty. The component
+ * uses this for the row highlight, aria-current and the auto-scroll.
+ */
+export declare function activeRailIndex(chapters: {
+    startSec: number;
+}[], t: number): number;

package/dist/video/chapterRail.js

@@ -0,0 +1,79 @@
+/**
+ * Chapter rail state (mos-777hj) — the pure half of VideoPlayer's opt-in
+ * `chapterRail: 'side'` pane: one row per chapter (title, time, status dot,
+ * summary), the active row tracking the playhead, a progress fill inside the
+ * active row and a played check once the playhead moves past a chapter's end.
+ *
+ * The component owns the DOM (rows, click-to-seek-and-play, listNav, sticky
+ * column, small-screen chip strip); everything derivable from
+ * (chapters, duration, playhead) lives HERE so it is node-testable under
+ * `npm run test:unit` — same discipline as band.ts / transcriptWindow.ts.
+ *
+ * Chapter ends: a chapter without an explicit `endSec` runs to the NEXT
+ * chapter's start; the last one runs to the media duration when known. With
+ * no duration and no following chapter the chapter is open-ended — its row
+ * simply never shows a played check or progress (division guards to 0).
+ */
+const STATUS_VALUES = ['info', 'success', 'warning', 'error'];
+function statusOf(value) {
+    return value != null && STATUS_VALUES.includes(value)
+        ? value
+        : null;
+}
+function clamp01(n) {
+    if (!Number.isFinite(n))
+        return 0;
+    return n < 0 ? 0 : n > 1 ? 1 : n;
+}
+/**
+ * The rail's rows for one playhead instant. `chapters` must be sorted by
+ * startSec (the component passes its `sortedChapters`); entries with a
+ * non-finite start are dropped, mirroring sortChapters' own filter.
+ *
+ * `t` before the first chapter (or exactly on it) marks that first chapter
+ * active with progress from its own start; there is no "before the program"
+ * row — the program starts at its first chapter.
+ */
+export function railChapters(chapters, durationSec, t) {
+    const rows = [];
+    for (let i = 0; i < chapters.length; i++) {
+        const c = chapters[i];
+        if (!c || !Number.isFinite(c.startSec) || c.startSec < 0)
+            continue;
+        const next = chapters[i + 1];
+        let end = c.endSec;
+        if (end == null || !Number.isFinite(end) || end <= c.startSec) {
+            end = next && Number.isFinite(next.startSec) ? next.startSec : durationSec;
+        }
+        if (end == null || !Number.isFinite(end) || end < c.startSec)
+            end = c.startSec;
+        const active = t >= c.startSec && (i === chapters.length - 1 || t < chapters[i + 1].startSec);
+        const span = end - c.startSec;
+        const progress = active && span > 0 ? clamp01((t - c.startSec) / span) : 0;
+        rows.push({
+            startSec: c.startSec,
+            endSec: end,
+            title: c.title,
+            summary: c.summary ?? null,
+            status: statusOf(c.status),
+            played: t >= end && end > c.startSec,
+            progress
+        });
+    }
+    return rows;
+}
+/**
+ * Index of the row containing `t` (the LAST chapter whose startSec <= t), or
+ * -1 when `t` sits before every chapter / the list is empty. The component
+ * uses this for the row highlight, aria-current and the auto-scroll.
+ */
+export function activeRailIndex(chapters, t) {
+    let idx = -1;
+    for (let i = 0; i < chapters.length; i++) {
+        if (chapters[i].startSec <= t)
+            idx = i;
+        else
+            break;
+    }
+    return idx;
+}

package/dist/video/keys.d.ts

@@ -20,7 +20,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' | 'bookmarks' | 'transcript' | 'comments' | 'night' | 'settings';
+    when?: 'chapters' | 'rail' | 'bookmarks' | 'transcript' | 'comments' | 'night' | 'settings';
 }
 /** Order follows the help overlay: transport, seek, volume, speed, structure. */
 export declare const PLAYER_KEYS: PlayerKeyRow[];

package/dist/video/keys.js

@@ -23,6 +23,9 @@ export const PLAYER_KEYS = [
     { keys: 'Backspace', description: 'Reset speed to 1×' },
     { keys: '< / >', description: 'Frame step (pauses; ~1/30s per press)' },
     { keys: '[ / ]', description: 'Previous / next chapter', when: 'chapters' },
+    // mos-777hj — the rail's own listNav motions, active only while the rail
+    // holds focus (the same keys drive seek/play-pause everywhere else).
+    { keys: 'j / k / Enter', description: 'Chapter rail: move / play chapter', when: 'rail' },
     // Shift+[ / Shift+] — the chapter keys' shifted twins, so "structure"
     // and "people's reactions to it" sit under one hand (mos-5lzns.30).
     { keys: '{ / }', description: 'Previous / next comment', when: 'comments' },

package/dist/video/types.d.ts

@@ -17,6 +17,16 @@ export interface VideoChapter {
     title: string;
     /** Optional captured still, shown in the band's hover card. */
     thumbUrl?: string | null;
+    /**
+     * Chapter end, seconds. Absent (mos-777hj rail) the chapter runs to the
+     * NEXT chapter's start — or the media duration for the last one. The rail
+     * uses it for the played check and the progress fill; the band ignores it.
+     */
+    endSec?: number | null;
+    /** One-line summary shown under the title in the chapter rail. */
+    summary?: string | null;
+    /** Rail status dot tone (DaisyUI semantic) — null renders no dot. */
+    status?: 'info' | 'success' | 'warning' | 'error' | null;
 }
 /** A diarized turn (or an ad read, `ad: true`). Structurally accepts meeting data. */
 export interface VideoSpeakerTurn {

package/package.json

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