@joewinke/jatui 0.47.0 → 0.49.0

package/CLAUDE.md

@@ -177,7 +177,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 take optional `progress` (0–100): an upload ring draws around the tile and a tiny % occupies the remove-× corner, cross-fading into the × at 100 (same slot, no layout shift; per-tile `role="progressbar"`). | `items: ThumbnailItem[]` (`{id, url?, alt, progress?}`), `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. A double-click on the picture toggles fullscreen (band transport; with native controls the browser owns the gesture), a buffering spinner shows while the media is waiting, and volume/mute survive a reload through `settingsStore` (else guarded localStorage). **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?` |
+| `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. A double-click on the picture toggles fullscreen (band transport; with native controls the browser owns the gesture), a buffering spinner shows while the media is waiting, and volume/mute survive a reload through `settingsStore` (else guarded localStorage). **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), `theaterMode?` (`'width'` default — the host widens its page \| `'fill'` — the player becomes a fixed full-viewport dialog: `role="dialog"` + `aria-modal`, page scroll locked, Tab trapped, Esc/the button exits and returns focus, largest 16:9 stage that fits, transcript beside it ≥64rem else below, z from `--jatui-z-theater`; a remembered theater never fills on load, only a viewer gesture), `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/README.md

@@ -32,7 +32,7 @@ Key contract points:
 
 - **Gesture-gated** — `engine.play(id)` must run inside a click/keydown handler; it rejects otherwise. The AudioContext closes itself ~3 s after stop, and a play inside that window fades back in instead of restarting.
 - **Scape contract** — `{ id, label, group, description?, build(ctx) }`; `build` connects into `ctx.input` (never straight to `destination`), gets the shared `ctx.breath` clock and a lookahead scheduler. Scapes are re-buildable and tear themselves down on `stop`.
-- **Playlist scapes** — per-host, never in the default set. Build one with `createPlaylistScape({ id, label, manifestUrl })` and `engine.register()` it; the manifest is fetched lazily once on the first play, tracks stream through the master chain with gain-ramp crossfades, and the returned `PlaylistScape` adds `state()/subscribe()/skip()/setShuffle()` for the UI. Manifest shape (`title` optional; `license` and `composer` required on every track):
+- **Playlist scapes** — per-host, never in the default set. Build one with `createPlaylistScape({ id, label, manifestUrl })` and `engine.register()` it; the manifest is fetched lazily once on the first play, tracks stream through the master chain with gain-ramp crossfades, and the returned `PlaylistScape` adds `state()/subscribe()/skip()/setShuffle()` for the UI. Manifest shape (`title` optional at the manifest level; every track requires `title`, `composer`, `url` and `license` — tracks missing any are dropped — with `performer` and `sourceUrl` optional):
 
 ```json
 {

package/dist/artifact-blocks/blocks/transcript/TranscriptBlock.svelte

@@ -19,6 +19,10 @@
    *     play/pause, time, speed and volume, so the native control bar (a
    *     second timeline) never renders. Audio has no stage at all
    *     (`kind="audio"`); video keeps its stage at its intrinsic ratio.
+   *   - video breaks out of the reading column like a wide table (def.wide
+   *     agrees), and its theater fills the browser window
+   *     (`theaterMode="fill"`) — an artifact page has no wider layout to
+   *     switch to. Audio stays in the column.
    *   - resumeKey ties "continue where you left off" to this artifact block,
    *     so a review round survives closing the tab.
    *
@@ -78,7 +82,7 @@
   }
 </script>
 
-<section class="artifact-transcript w-full">
+<section class="artifact-transcript w-full" class:tr-wide={isVideo}>
   {#if params.title || params.note}
     <header class="mb-3">
       {#if params.title}
@@ -109,6 +113,7 @@
       chapters={vChapters}
       markers={vMarkers}
       transcriptPosition={isVideo ? "side" : "below"}
+      theaterMode={isVideo ? "fill" : "width"}
       transcriptMaxHeight="24rem"
       {resumeKey}
     />
@@ -167,3 +172,16 @@
     </section>
   {/if}
 </section>
+
+<style>
+  /* Video: break out of the artifact page's reading column the way a wide
+     table does (TableBlock's .tb-wide — the same formula, so the two line
+     up): centred on the column, capped at 80rem, 1.5rem inside the page
+     view's MEASURED width (--artifact-page-w). Only that page opts in;
+     pinned/embedded hosts keep the block in its column. */
+  :global([data-artifact-page]) .tr-wide {
+    --tr-w: max(100%, min(var(--artifact-page-w, 100%) - 3rem, 80rem));
+    width: var(--tr-w);
+    margin-inline: calc((100% - var(--tr-w)) / 2);
+  }
+</style>

package/dist/artifact-blocks/blocks/transcript/block.js

@@ -81,6 +81,9 @@ const def = {
     component: TranscriptBlock,
     // mos-8fvt9: the section's Listen + comment sit on the heading row.
     hostsTools: (p) => Boolean(p.title),
+    // jatui-c5uob: video breaks out of the reading column (TranscriptBlock's
+    // .tr-wide); audio stays in it. media.type defaults to audio.
+    wide: (p) => p.media?.type === "video",
     example: EXAMPLE,
 };
 export default def;

package/dist/components/VideoPlayer.svelte

@@ -256,6 +256,7 @@
 	} from '../video/presence';
 	import type { ResumePoint } from '../video/advisors/resume-point';
 	import { idleDetectionSupported } from '../video/presence';
+	import { lockPageScroll, resolveTheaterMode, trapFillTab, type TheaterMode } from '../video/theaterFill';
 	import {
 		coerce,
 		createSettingsSession,
@@ -301,6 +302,7 @@
 		transcriptMaxHeight,
 		followResumeMs = FOLLOW_RESUME_IDLE_MS,
 		theater = $bindable(false),
+		theaterMode = 'width',
 		theaterButton = true,
 		onTheaterChange,
 		/**
@@ -495,6 +497,18 @@
 		 * host's default; a remembered choice wins.
 		 */
 		theater?: boolean;
+		/**
+		 * What theater does (jatui-c5uob). `'width'` (default) is the above:
+		 * the host widens its page. `'fill'` makes the player itself a fixed
+		 * full-viewport dialog (`role="dialog"`, `aria-modal`): the page stops
+		 * scrolling, Tab stays inside the player, Escape or the theater button
+		 * exits and gives focus back. The video is the largest 16:9 box that
+		 * fits (other ratios letterbox), a transcript sits beside it from
+		 * 64rem and below it under that. Fullscreen stays monitor fullscreen.
+		 * A REMEMBERED theater never opens the overlay on load — only the
+		 * viewer's own gesture (button, `t`, settings panel) fills the window.
+		 */
+		theaterMode?: TheaterMode;
 		/** Show the theater button + `t` key (video only; default true). */
 		theaterButton?: boolean;
 		/** The viewer toggled theater mode (button, `t`, settings panel). */
@@ -2338,7 +2352,7 @@
 	let rootEl: HTMLDivElement | undefined = $state();
 
 	/** Land one coerced value: bindables are written, everything else overlays its prop. */
-	function applySetting(id: string, v: SettingValue) {
+	function applySetting(id: string, v: SettingValue, source?: 'user' | 'store') {
 		if (id === 'night.mode') {
 			if (night !== undefined && night !== v) {
 				night = v as NightMode;
@@ -2352,6 +2366,7 @@
 		}
 		if (id === 'player.theater') {
 			if (!settingsStore) localTheaterStore.set(id, v);
+			if (source === 'user') fillRequested = v === true;
 			if (theater !== v) {
 				theater = v as boolean;
 				onTheaterChange?.(theater);
@@ -2368,7 +2383,7 @@
 			createSettingsSession({
 				store,
 				onValue: (id, v, source) => {
-					applySetting(id, v);
+					applySetting(id, v, source);
 					if (source === 'user') onSettingChange?.(id, v);
 				}
 			})
@@ -2388,6 +2403,31 @@
 	const localTheaterStore = localSettingsStore();
 	const theaterAvailable = $derived(!isAudio && theaterButton);
 	const theaterOn = $derived(theaterAvailable && theater);
+	// Fill mode (jatui-c5uob): the overlay is open only after a viewer
+	// gesture in THIS page — the remembered `player.theater` alone never
+	// covers the page on load. `theaterActive` is what the root and the
+	// button show: in fill mode, whether the overlay is up.
+	const fillMode = $derived(resolveTheaterMode(theaterMode) === 'fill');
+	let fillRequested = $state(false);
+	const filling = $derived(fillMode && theaterOn && fillRequested);
+	const theaterActive = $derived(fillMode ? filling : theaterOn);
+	$effect(() => {
+		if (!theaterOn && fillRequested) fillRequested = false;
+	});
+	// While filling: the page under the overlay doesn't scroll, and focus
+	// goes back where it was when the overlay closes.
+	$effect(() => {
+		if (!filling || typeof document === 'undefined') return;
+		const returnTo = document.activeElement as HTMLElement | null;
+		const release = lockPageScroll(document);
+		const root = untrack(() => rootEl);
+		if (root && !root.contains(document.activeElement)) root.focus();
+		return () => {
+			release();
+			const back = returnTo && returnTo.isConnected ? returnTo : untrack(() => rootEl);
+			back?.focus({ preventScroll: true });
+		};
+	});
 	$effect(() => {
 		if (!theaterAvailable || settingsStore) return;
 		untrack(() => {
@@ -2398,7 +2438,8 @@
 	});
 	function toggleTheater() {
 		if (!theaterAvailable) return;
-		const next = !theaterOn;
+		const next = !theaterActive;
+		if (fillMode) fillRequested = next;
 		if (settingsSession) settingsSession.change('player.theater', next);
 		else applySetting('player.theater', next);
 		flashOsd(next ? 'Theater mode' : 'Default view');
@@ -3069,6 +3110,31 @@
 	 * ADVERTISED when the data exists — a documented key that does nothing is
 	 * the one thing a keymap must never be.
 	 */
+	/** Fill theater (jatui-c5uob): Tab stays inside the player, and Escape
+	 *  exits — after the overlays that own Escape (help, search, settings,
+	 *  band zoom) have had it, and never while the stage is fullscreen. */
+	function onRootKeyDownFill(e: KeyboardEvent) {
+		if (filling && rootEl) {
+			if (e.key === 'Tab') {
+				trapFillTab(rootEl, e);
+				return;
+			}
+			if (
+				e.key === 'Escape' &&
+				!e.defaultPrevented &&
+				!keysOpen &&
+				!searchOpen &&
+				!settingsOpen &&
+				!isFullscreen
+			) {
+				e.preventDefault();
+				toggleTheater();
+				return;
+			}
+		}
+		onRootKeyDown(e);
+	}
+
 	function onRootKeyDown(e: KeyboardEvent) {
 		// The band's slider handler (and the help overlay) own their keys and
 		// preventDefault them — without this guard an ArrowLeft with the band
@@ -3514,9 +3580,12 @@
 <div
 	class="vp-root {className}"
 	bind:this={rootEl}
-	class:vp-side={transcriptLayout === 'side' && !theaterOn && sortedSegments.length > 0}
-	class:vp-theater={theaterOn}
-	data-theater={theaterAvailable ? String(theaterOn) : undefined}
+	class:vp-side={transcriptLayout === 'side' && !theaterActive && sortedSegments.length > 0}
+	class:vp-theater={theaterActive}
+	class:vp-fill={filling}
+	class:vp-fill-transcript={filling && sortedSegments.length > 0 && transcriptLayout !== 'hidden'}
+	data-theater={theaterAvailable ? String(theaterActive) : undefined}
+	data-theater-mode={theaterAvailable ? (fillMode ? 'fill' : 'width') : undefined}
 	class:vp-rail-side={railOn}
 	class:vp-one-axis={nativeBarHidden}
 	class:vp-band-transport={bandTransport}
@@ -3526,10 +3595,11 @@
 	class:vp-night-surround={surroundMix > 0.001}
 	style:--vp-night-surround={surroundMix > 0.001 ? surroundMix.toFixed(3) : undefined}
 	data-band-axis={currentBandState.axis}
-	role="region"
-	aria-label={isAudio ? 'Audio player' : 'Video player'}
+	role={filling ? 'dialog' : 'region'}
+	aria-modal={filling ? 'true' : undefined}
+	aria-label={isAudio ? 'Audio player' : filling ? 'Video player, theater' : 'Video player'}
 	tabindex="-1"
-	onkeydown={onRootKeyDown}
+	onkeydown={onRootKeyDownFill}
 	onpointerdowncapture={maybeAskIdle}
 	onpointerupcapture={maybeAskIdle}
 	onclickcapture={maybeAskIdle}
@@ -3878,10 +3948,10 @@
 					<button
 						type="button"
 						class="vp-theater-btn"
-						class:active={theaterOn}
+						class:active={theaterActive}
 						aria-label="Theater mode"
-						aria-pressed={theaterOn}
-						title="{theaterOn ? 'Default view' : 'Theater mode'} · t"
+						aria-pressed={theaterActive}
+						title="{theaterActive ? (fillMode ? 'Exit theater · t or Esc' : 'Default view · t') : '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">
@@ -4606,6 +4676,137 @@
 		}
 	}
 
+	/* ── Fill theater (jatui-c5uob) ──────────────────────────────────────
+	   theaterMode="fill": the player IS the overlay — fixed to the viewport
+	   above the page (z from --jatui-z-theater). The stage is the largest
+	   16:9 box its cell can hold (size container units: 100cqw wide, or
+	   100cqh × 16/9 when the height is what runs out); a source of another
+	   ratio letterboxes inside it. A transcript sits beside the video from
+	   64rem and below it under that; the chapter rail keeps its column.
+	   Placed after the rail rules so the same-specificity grid wins. */
+	.vp-root.vp-fill {
+		position: fixed;
+		inset: 0;
+		z-index: var(--jatui-z-theater, 9040);
+		display: grid;
+		grid-template-columns: minmax(0, 1fr);
+		grid-template-rows: minmax(0, 1fr);
+		grid-auto-rows: auto;
+		grid-template-areas: 'main' 'rail' 'below' 'transcript';
+		align-items: stretch;
+		gap: var(--jatui-space-lg, 12px);
+		margin: 0;
+		border: 0;
+		border-radius: 0;
+		padding: var(--jatui-space-xl, 16px);
+		background: var(--color-base-300);
+		overflow: hidden;
+	}
+
+	.vp-root.vp-fill > .vp-main {
+		grid-area: main;
+		min-height: 0;
+	}
+
+	.vp-root.vp-fill > .vp-chapters {
+		grid-area: rail;
+	}
+
+	.vp-root.vp-fill > .vp-below-stage {
+		grid-area: below;
+	}
+
+	.vp-root.vp-fill > .vp-transcript-wrap {
+		grid-area: transcript;
+		min-height: 0;
+		max-height: 40vh;
+		max-height: 40dvh;
+	}
+
+	.vp-root.vp-fill .vp-transcript {
+		max-height: none;
+		flex: 1 1 auto;
+		min-height: 0;
+	}
+
+	.vp-fill .vp-stage-wrap {
+		flex: 1 1 0;
+		min-height: 0;
+		container-type: size;
+		display: flex;
+		flex-direction: column;
+		align-items: center;
+		justify-content: center;
+	}
+
+	.vp-fill .vp-stage,
+	.vp-fill .vp-stage.vp-stage-locked {
+		flex: none;
+		width: min(100cqw, 100cqh * 16 / 9);
+		aspect-ratio: 16 / 9;
+		background: var(--color-neutral);
+		border-radius: var(--jatui-radius-field, 0.25rem);
+		overflow: hidden;
+	}
+
+	.vp-fill .vp-stage .vp-video {
+		position: absolute;
+		inset: 0;
+		width: 100%;
+		height: 100%;
+		object-fit: contain;
+		border-radius: 0;
+	}
+
+	@media (min-width: 64rem) {
+		.vp-root.vp-fill.vp-fill-transcript {
+			grid-template-columns: minmax(0, 1fr) minmax(20rem, 28rem);
+			grid-template-rows: minmax(0, 1fr) auto;
+			grid-template-areas:
+				'main transcript'
+				'below transcript';
+		}
+
+		.vp-root.vp-fill.vp-rail-side {
+			grid-template-columns: minmax(0, 1fr) minmax(11rem, 14rem);
+			grid-template-rows: minmax(0, 1fr) auto;
+			grid-template-areas:
+				'main rail'
+				'below rail';
+		}
+
+		.vp-root.vp-fill.vp-fill-transcript.vp-rail-side {
+			grid-template-columns: minmax(0, 1fr) minmax(20rem, 28rem) minmax(11rem, 14rem);
+			grid-template-areas:
+				'main transcript rail'
+				'below transcript rail';
+		}
+
+		.vp-root.vp-fill > .vp-transcript-wrap {
+			max-height: none;
+		}
+
+		.vp-root.vp-fill.vp-rail-side > .vp-chapters {
+			position: static;
+			max-height: none;
+			min-height: 0;
+			overflow-y: auto;
+		}
+	}
+
+	/* Entrance: a short fade, only when motion is welcome. */
+	@media (prefers-reduced-motion: no-preference) {
+		.vp-root.vp-fill {
+			animation: vp-fill-in var(--motion-enter, 200ms) var(--motion-glide, ease-out);
+		}
+	}
+
+	@keyframes vp-fill-in {
+		from {
+			opacity: 0;
+		}
+	}
+
 	.vp-stage {
 		position: relative;
 	}

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

@@ -75,6 +75,7 @@ import { type NightMode, type NightWindow } from '../video/night/clock';
 import { type AudioBrokenReason, type AudioState } from '../video/audio';
 import { type FlipSource, type VideoResumeStore, type WindDownState } from '../video/presence';
 import type { ResumePoint } from '../video/advisors/resume-point';
+import { type TheaterMode } from '../video/theaterFill';
 import { type SettingValue, type VideoSettingsStore } from '../video/settings';
 type $$ComponentProps = {
     src: string;
@@ -202,6 +203,18 @@ type $$ComponentProps = {
      * host's default; a remembered choice wins.
      */
     theater?: boolean;
+    /**
+     * What theater does (jatui-c5uob). `'width'` (default) is the above:
+     * the host widens its page. `'fill'` makes the player itself a fixed
+     * full-viewport dialog (`role="dialog"`, `aria-modal`): the page stops
+     * scrolling, Tab stays inside the player, Escape or the theater button
+     * exits and gives focus back. The video is the largest 16:9 box that
+     * fits (other ratios letterbox), a transcript sits beside it from
+     * 64rem and below it under that. Fullscreen stays monitor fullscreen.
+     * A REMEMBERED theater never opens the overlay on load — only the
+     * viewer's own gesture (button, `t`, settings panel) fills the window.
+     */
+    theaterMode?: TheaterMode;
     /** Show the theater button + `t` key (video only; default true). */
     theaterButton?: boolean;
     /** The viewer toggled theater mode (button, `t`, settings panel). */

package/dist/index.d.ts

@@ -24,6 +24,8 @@ export { LISTEN_KEYS } from './listen/keys';
 export { LISTEN_SPEEDS, SPEED_FLOOR, SPEED_CEIL, clampSpeed, stepSpeed, formatListenSpeed } from './listen/prefs';
 export type { VideoChapter, VideoSpeakerTurn, VideoTranscriptSegment, VideoBookmark, VideoWaveform, VideoSpeakerTalkTime, VideoLumaTrack, VideoMarker, BandState, BandAxis, NightMode, NightWindow, AudioState, AudioStatus, AudioBrokenReason, VideoAdSpan, RateReport, WindDownState, WindDownPhase, PresenceSource, VideoResumeStore, FlipSource, } from './components/VideoPlayer.svelte';
 export { speakerRateMap, toRateTurns, toRateSegments } from './video/rate';
+export type { TheaterMode } from './video/theaterFill';
+export { lockPageScroll, trapFillTab, fillFocusables, resolveTheaterMode } from './video/theaterFill';
 export { idleDetectionSupported, idleDetectionPermission, requestIdleDetection, localResumeStore, flipOpen, flipClose, clearPoster, type IdlePermission } from './video/presence';
 export { VIDEO_SETTINGS, SETTING_GROUPS, settingSpec, settingValue, coerce as coerceVideoSetting, memorySettingsStore, panelGroups as videoSettingsGroups, formatSettingValue, type VideoSettingsStore, type SettingSpec as VideoSettingSpec, type SettingValue as VideoSettingValue, type SettingOption as VideoSettingOption, type SettingWhen as VideoSettingWhen, type SettingAvailability as VideoSettingAvailability } from './video/settings';
 export { buildSilenceMap, boostAt, estimateSaving, type SilenceMap, type SilenceWave, type SilenceOpts, type BoostOpts } from './video/advisors/smart-speed';

package/dist/index.js

@@ -43,6 +43,7 @@ export { LISTEN_SPEEDS, SPEED_FLOOR, SPEED_CEIL, clampSpeed, stepSpeed, formatLi
 // under `speakerPace` (manual beats measured), for a host drawing its own
 // per-speaker speed UI.
 export { speakerRateMap, toRateTurns, toRateSegments } from './video/rate';
+export { lockPageScroll, trapFillTab, fillFocusables, resolveTheaterMode } from './video/theaterFill';
 // Presence (mos-5lzns.34): the permission call a host makes from the click
 // that enables wind-down's desktop signal (the API needs a user gesture),
 // the default resume store, and the FLIP pair for a host animating its own

package/dist/styles/tokens.css

@@ -28,6 +28,10 @@
 
 	/* Border — depth comes from tonal surfaces + 1px borders, not shadows */
 	--jatui-border-w: 1px;
+
+	/* Stacking — full-viewport surfaces (VideoPlayer's fill theater). A
+	   host's --z-lightbox tier wins; 9040 matches MediaLightbox's default. */
+	--jatui-z-theater: var(--z-lightbox, 9040);
 }
 
 /*

package/dist/video/theaterFill.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Browser-fill theater (jatui-c5uob, upstreamed from MOS mos-wyjyh).
+ *
+ * `theaterMode="fill"` turns VideoPlayer's theater into a fixed,
+ * full-viewport dialog instead of asking the host to widen its page. The
+ * component owns the markup and CSS; this module holds the DOM plumbing a
+ * modal surface needs, kept framework-free so it can be tested on its own:
+ *
+ *   - `resolveTheaterMode` — the prop's never-throws coercion;
+ *   - `fillFocusables` / `trapFillTab` — Tab and Shift+Tab cycle inside the
+ *     player while it fills the window;
+ *   - `lockPageScroll` — the page under the overlay doesn't scroll. Counted,
+ *     so two filled players (or a player and a host modal using the same
+ *     lock) release it only when the last one lets go.
+ */
+export type TheaterMode = 'width' | 'fill';
+/** Unknown or missing values are today's behaviour: `'width'`. */
+export declare function resolveTheaterMode(v: unknown): TheaterMode;
+/** Tab stops inside `root`, in document order. Hidden, inert and
+ *  `tabindex="-1"` elements are skipped. */
+export declare function fillFocusables(root: Element): HTMLElement[];
+/**
+ * Keep Tab inside `root`. Call it from a keydown handler; it returns true
+ * (and preventDefaults) only when it moved focus itself — at the first or
+ * last stop, when focus has escaped the root, or when the root has no stops
+ * at all. Otherwise the browser's own Tab order is left to run.
+ */
+export declare function trapFillTab(root: HTMLElement, e: KeyboardEvent): boolean;
+/**
+ * Stop the page from scrolling behind a full-window surface. The scrollbar's
+ * width is put back as padding so the page doesn't shift sideways. Returns
+ * the release function; calling it twice is harmless.
+ */
+export declare function lockPageScroll(doc: Document): () => void;

package/dist/video/theaterFill.js

@@ -0,0 +1,117 @@
+/**
+ * Browser-fill theater (jatui-c5uob, upstreamed from MOS mos-wyjyh).
+ *
+ * `theaterMode="fill"` turns VideoPlayer's theater into a fixed,
+ * full-viewport dialog instead of asking the host to widen its page. The
+ * component owns the markup and CSS; this module holds the DOM plumbing a
+ * modal surface needs, kept framework-free so it can be tested on its own:
+ *
+ *   - `resolveTheaterMode` — the prop's never-throws coercion;
+ *   - `fillFocusables` / `trapFillTab` — Tab and Shift+Tab cycle inside the
+ *     player while it fills the window;
+ *   - `lockPageScroll` — the page under the overlay doesn't scroll. Counted,
+ *     so two filled players (or a player and a host modal using the same
+ *     lock) release it only when the last one lets go.
+ */
+/** Unknown or missing values are today's behaviour: `'width'`. */
+export function resolveTheaterMode(v) {
+    return v === 'fill' ? 'fill' : 'width';
+}
+const FOCUSABLE = [
+    'a[href]',
+    'area[href]',
+    'button:not([disabled])',
+    'input:not([disabled]):not([type="hidden"])',
+    'select:not([disabled])',
+    'textarea:not([disabled])',
+    'video[controls]',
+    'audio[controls]',
+    '[contenteditable=""]',
+    '[contenteditable="true"]',
+    '[tabindex]'
+].join(',');
+/** Tab stops inside `root`, in document order. Hidden, inert and
+ *  `tabindex="-1"` elements are skipped. */
+export function fillFocusables(root) {
+    const out = [];
+    for (const el of root.querySelectorAll(FOCUSABLE)) {
+        if (el.tabIndex < 0)
+            continue;
+        if (el.closest('[hidden],[inert]'))
+            continue;
+        // checkVisibility catches display:none / visibility:hidden ancestors;
+        // engines without it (jsdom) count the element as visible.
+        const check = el.checkVisibility;
+        if (check && !check.call(el, { visibilityProperty: true }))
+            continue;
+        out.push(el);
+    }
+    return out;
+}
+/**
+ * Keep Tab inside `root`. Call it from a keydown handler; it returns true
+ * (and preventDefaults) only when it moved focus itself — at the first or
+ * last stop, when focus has escaped the root, or when the root has no stops
+ * at all. Otherwise the browser's own Tab order is left to run.
+ */
+export function trapFillTab(root, e) {
+    if (e.key !== 'Tab' || e.altKey || e.ctrlKey || e.metaKey)
+        return false;
+    const stops = fillFocusables(root);
+    const active = root.ownerDocument.activeElement;
+    const inside = !!active && root.contains(active);
+    if (stops.length === 0) {
+        e.preventDefault();
+        root.focus();
+        return true;
+    }
+    const first = stops[0];
+    const last = stops[stops.length - 1];
+    let next = null;
+    if (!inside || active === root)
+        next = e.shiftKey ? last : first;
+    else if (e.shiftKey && active === first)
+        next = last;
+    else if (!e.shiftKey && active === last)
+        next = first;
+    if (!next)
+        return false;
+    e.preventDefault();
+    next.focus();
+    return true;
+}
+const locks = new WeakMap();
+/**
+ * Stop the page from scrolling behind a full-window surface. The scrollbar's
+ * width is put back as padding so the page doesn't shift sideways. Returns
+ * the release function; calling it twice is harmless.
+ */
+export function lockPageScroll(doc) {
+    const html = doc.documentElement;
+    let state = locks.get(doc);
+    if (!state) {
+        const win = doc.defaultView;
+        const gutter = win ? Math.max(0, win.innerWidth - html.clientWidth) : 0;
+        state = { count: 0, overflow: html.style.overflow, paddingRight: html.style.paddingRight };
+        locks.set(doc, state);
+        html.style.overflow = 'hidden';
+        if (gutter > 0)
+            html.style.paddingRight = `${gutter}px`;
+    }
+    state.count++;
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        const s = locks.get(doc);
+        if (!s)
+            return;
+        s.count--;
+        if (s.count > 0)
+            return;
+        html.style.overflow = s.overflow;
+        html.style.paddingRight = s.paddingRight;
+        locks.delete(doc);
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joewinke/jatui",
-  "version": "0.47.0",
+  "version": "0.49.0",
   "private": false,
   "description": "Shared Svelte 5 component library for JAT projects",
   "type": "module",
@@ -87,6 +87,11 @@
       "types": "./dist/artifact-blocks/index.d.ts",
       "svelte": "./dist/artifact-blocks/index.js",
       "default": "./dist/artifact-blocks/index.js"
+    },
+    "./ambience": {
+      "types": "./dist/ambience/index.d.ts",
+      "svelte": "./dist/ambience/index.js",
+      "default": "./dist/ambience/index.js"
     }
   },
   "files": [