@joewinke/jatui 0.2.30 → 0.2.32

package/dist/actions/railNav.js

@@ -84,6 +84,16 @@ export function cycle(list, current, dir) {
 const BUMP_DURATION_MS = 280;
 const RAIL_FOCUS_CLASS = 'rail-focus';
 const RAIL_CYCLED_CLASS = 'rail-cycled';
+/** `<input>` types whose vertical arrows natively step the value (spinner / picker). */
+const STEPPER_INPUT_TYPES = new Set([
+    'number',
+    'range',
+    'date',
+    'time',
+    'month',
+    'week',
+    'datetime-local',
+]);
 function resolveOrder(opts) {
     return typeof opts.order === 'function' ? opts.order() : opts.order;
 }
@@ -213,6 +223,13 @@ function makeController(optsRef) {
         const isTextField = !!el &&
             (tag === 'INPUT' || tag === 'TEXTAREA' || el.isContentEditable === true);
         const isMultiline = !!el && (tag === 'TEXTAREA' || el.isContentEditable === true);
+        const inputType = tag === 'INPUT' ? (el.type || '').toLowerCase() : '';
+        // A <select> cycles its value with arrows on BOTH axes, and a radio moves
+        // within its `name` group on both axes — the rail must yield entirely or it
+        // silently drives an unrelated rung while the user thinks they're picking a value.
+        const ownsBothArrowAxes = tag === 'SELECT' || inputType === 'radio';
+        const blocksVerticalArrows = isMultiline || ownsBothArrowAxes || STEPPER_INPUT_TYPES.has(inputType);
+        const blocksHorizontalArrows = isTextField || ownsBothArrowAxes;
         const hasMod = event.metaKey || event.ctrlKey || event.altKey;
         // Modal trap — stop non-text keystrokes from bubbling to window-level page
         // listeners (e.g., a listNav attached to `window`). Text-field keystrokes
@@ -245,13 +262,13 @@ function makeController(optsRef) {
         const popoverOpen = opts.isPopoverOpen?.() ?? false;
         if (!hasMod && !popoverOpen) {
             // Vertical: ArrowDown / j step down; ArrowUp / k step up.
-            // j / k are blocked in ANY text field; arrows are blocked only inside
-            // multiline fields so the caret can still move line-by-line.
+            // j / k are blocked in ANY text field (they'd type a letter); arrows are
+            // blocked wherever the control owns them natively.
             const goDown = event.key === 'ArrowDown' || event.key === 'j';
             const goUp = event.key === 'ArrowUp' || event.key === 'k';
             if (goDown || goUp) {
                 const isVimKey = event.key === 'j' || event.key === 'k';
-                const blocked = isVimKey ? isTextField : isMultiline;
+                const blocked = isVimKey ? isTextField : blocksVerticalArrows;
                 if (!blocked) {
                     event.preventDefault();
                     moveRung(goDown ? 1 : -1);
@@ -261,7 +278,7 @@ function makeController(optsRef) {
             // Horizontal: ArrowLeft / ArrowRight dispatch to `onAction`.
             // Skipped inside text fields so caret-left / caret-right keep working.
             if ((event.key === 'ArrowLeft' || event.key === 'ArrowRight') &&
-                !isTextField) {
+                !blocksHorizontalArrows) {
                 event.preventDefault();
                 const attr = resolveAttr(opts);
                 // Prefer the element that actually has DOM focus, then fall back to

package/dist/components/Flythrough.svelte

@@ -0,0 +1,173 @@
+<script lang="ts">
+	/**
+	 * Flythrough — a decorative, aspect-locked motion embed for seedance/kenburns
+	 * flythrough clips (the "camera drifts over the scene" B-roll that heads a
+	 * lesson or a section). Presentation primitive per the unified-video-pipeline
+	 * PRD, sibling to <VideoPlayer> (the full player) and <LessonEmbed>.
+	 *
+	 * It is NOT a player: no controls, no scrubber, no audio. A flythrough is
+	 * ambient — it plays muted, loops, and asks for no interaction. That framing
+	 * decides every behaviour here:
+	 *
+	 *  · It autoplays muted + loops by default (that's what "flythrough" means).
+	 *  · Under `prefers-reduced-motion: reduce` it does NOT play — it shows a still
+	 *    poster instead. Ambient motion is exactly the motion that preference asks
+	 *    to suppress, and a flythrough always has a poster to fall back TO
+	 *    (`reducedMotionPoster` overrides `poster` for that still if the host wants
+	 *    a hand-picked frame rather than the video's cover art).
+	 *  · The box is aspect-locked from the first frame (poster convention) so the
+	 *    poster → decoded-frame swap is a cross-fade in place, never a layout shove.
+	 *
+	 * Contract (shared asset conventions): takes only a decode-checked `src` and a
+	 * `poster.jpg` beside it. No ffmpeg in the browser; the clip is already CFR,
+	 * decode-clean and web-encoded upstream (`jat-video`).
+	 */
+	import { onMount, untrack } from 'svelte';
+
+	let {
+		src,
+		poster = null,
+		aspect = '16:9',
+		reducedMotionPoster = null,
+		autoplay = true,
+		loop = true,
+		alt = '',
+		class: className = ''
+	}: {
+		/** Decode-checked flythrough clip. */
+		src: string;
+		/** Cover art beside the clip — shown until the first frame decodes, and the
+		 *  still shown outright under reduced-motion (unless `reducedMotionPoster`
+		 *  supplies a different frame). */
+		poster?: string | null;
+		/** `"W:H"` | ratio number | null/"auto". Reserved from the first frame. */
+		aspect?: string | null;
+		/** A hand-picked still for the reduced-motion fallback. Falls back to `poster`. */
+		reducedMotionPoster?: string | null;
+		/** Play on mount (muted). Vetoed by `prefers-reduced-motion`. Default true. */
+		autoplay?: boolean;
+		/** Loop the clip. Default true — a flythrough is ambient. */
+		loop?: boolean;
+		/** Alt text for the reduced-motion still (a11y — the still is the content then). */
+		alt?: string;
+		class?: string;
+	} = $props();
+
+	const aspectRatioCss = $derived.by(() => {
+		const a = aspect;
+		if (a == null) return null;
+		const trimmed = String(a).trim();
+		if (trimmed === '' || trimmed === 'auto') return null;
+		const colon = trimmed.match(/^(\d+(?:\.\d+)?)\s*[:/]\s*(\d+(?:\.\d+)?)$/);
+		if (colon) {
+			const w = parseFloat(colon[1]);
+			const h = parseFloat(colon[2]);
+			if (w > 0 && h > 0) return `${w} / ${h}`;
+		}
+		const num = Number(trimmed);
+		if (Number.isFinite(num) && num > 0) return String(num);
+		return null;
+	});
+
+	let videoEl: HTMLVideoElement | undefined = $state();
+	let reduceMotion = $state(false);
+
+	/** Under reduce we render a poster still and never mount playback. */
+	const showStill = $derived(reduceMotion);
+	const stillSrc = $derived(reducedMotionPoster ?? poster);
+
+	onMount(() => {
+		let stop: (() => void) | undefined;
+		if (typeof window !== 'undefined' && window.matchMedia) {
+			const mq = window.matchMedia('(prefers-reduced-motion: reduce)');
+			reduceMotion = mq.matches;
+			const onChange = () => (reduceMotion = mq.matches);
+			mq.addEventListener('change', onChange);
+			stop = () => mq.removeEventListener('change', onChange);
+		}
+		return () => stop?.();
+	});
+
+	// Start playback once the element exists and motion is allowed. Imperative (not
+	// the native attribute) so a mid-session flip to "reduce" can pause it and a
+	// flip away can resume — the poster-still swap is handled by `showStill`.
+	let started = false;
+	$effect(() => {
+		const v = videoEl;
+		const play = autoplay && !reduceMotion && !showStill;
+		untrack(() => {
+			if (!v) return;
+			if (play && !started) {
+				started = true;
+				v.muted = true;
+				void v.play().catch(() => {});
+			} else if (!play && !v.paused) {
+				v.pause();
+			}
+		});
+	});
+</script>
+
+<div
+	class="ft-root {className}"
+	class:ft-locked={aspectRatioCss != null}
+	style={aspectRatioCss != null ? `--ft-aspect: ${aspectRatioCss};` : undefined}
+>
+	{#if showStill}
+		<!-- Reduced-motion fallback: the flythrough is content-free decoration, so the
+		     still IS the presentation. alt is host-supplied (usually empty for pure
+		     decoration). -->
+		{#if stillSrc}
+			<img class="ft-still" src={stillSrc} {alt} />
+		{:else}
+			<div class="ft-still ft-still-empty" aria-hidden="true"></div>
+		{/if}
+	{:else}
+		<video
+			bind:this={videoEl}
+			{src}
+			{loop}
+			muted
+			playsinline
+			poster={poster ?? undefined}
+			class="ft-video"
+			aria-hidden="true"
+		></video>
+	{/if}
+</div>
+
+<style>
+	/* Aspect-locked from the first frame (poster convention): the box owns its
+	   ratio before the video decodes, so poster → frame is an in-place swap. */
+	.ft-root {
+		position: relative;
+		width: 100%;
+		overflow: hidden;
+		background: var(--color-neutral);
+		border-radius: var(--jatui-radius-box, 0.5rem);
+	}
+
+	.ft-locked {
+		aspect-ratio: var(--ft-aspect);
+	}
+
+	.ft-video,
+	.ft-still {
+		display: block;
+		width: 100%;
+		height: 100%;
+		object-fit: cover;
+	}
+
+	/* When the box is aspect-locked the media fills it absolutely; unlocked, the
+	   media's intrinsic size drives the box height. */
+	.ft-locked .ft-video,
+	.ft-locked .ft-still {
+		position: absolute;
+		inset: 0;
+	}
+
+	.ft-still-empty {
+		background: var(--color-base-300, var(--color-neutral));
+	}
+</style>

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

@@ -0,0 +1,22 @@
+type $$ComponentProps = {
+    /** Decode-checked flythrough clip. */
+    src: string;
+    /** Cover art beside the clip — shown until the first frame decodes, and the
+     *  still shown outright under reduced-motion (unless `reducedMotionPoster`
+     *  supplies a different frame). */
+    poster?: string | null;
+    /** `"W:H"` | ratio number | null/"auto". Reserved from the first frame. */
+    aspect?: string | null;
+    /** A hand-picked still for the reduced-motion fallback. Falls back to `poster`. */
+    reducedMotionPoster?: string | null;
+    /** Play on mount (muted). Vetoed by `prefers-reduced-motion`. Default true. */
+    autoplay?: boolean;
+    /** Loop the clip. Default true — a flythrough is ambient. */
+    loop?: boolean;
+    /** Alt text for the reduced-motion still (a11y — the still is the content then). */
+    alt?: string;
+    class?: string;
+};
+declare const Flythrough: import("svelte").Component<$$ComponentProps, {}, "">;
+type Flythrough = ReturnType<typeof Flythrough>;
+export default Flythrough;

package/dist/components/LessonEmbed.svelte

@@ -0,0 +1,227 @@
+<script lang="ts" module>
+	/**
+	 * The demo-assemble `collection.json` shape (pinned from mardukos
+	 * `scripts/demo-assemble.mjs` writer + `welcome/[token]` reader, per
+	 * docs/edl-contract.md). Fields the writer emits with `_url` suffixes are
+	 * accepted alongside the reader's shorter aliases, so a manifest from either
+	 * side of the contract loads without a translation step.
+	 */
+
+	/** One beat's timing within a cut (for a future chapter rail; carried through). */
+	export interface CollectionBeat {
+		id: string | number;
+		name?: string;
+		start_sec?: number;
+		end_sec?: number;
+	}
+
+	/** A named output variant — one playable video. */
+	export interface CollectionCut {
+		id: string;
+		label?: string;
+		/** Assemble writes `blurb`; audience copy for the picker. */
+		blurb?: string;
+		duration_sec?: number;
+		/** The mp4. Writer/reader both use `url` (minio or repo-relative path). */
+		url: string;
+		/** Cover art. Writer emits `poster_url`; `poster` accepted as an alias. */
+		poster_url?: string;
+		poster?: string;
+		beats?: CollectionBeat[];
+	}
+
+	/** The `collection.json` manifest. */
+	export interface Collection {
+		template?: string;
+		prospect?: string | null;
+		brand_name?: string;
+		primary_color?: string;
+		cuts: CollectionCut[];
+	}
+
+	function cutPoster(c: CollectionCut): string | null {
+		return c.poster_url ?? c.poster ?? null;
+	}
+</script>
+
+<script lang="ts">
+	/**
+	 * LessonEmbed — renders a demo-assemble `collection.json`: a picker across the
+	 * named cuts with a <VideoPlayer> for the selected one. Presentation primitive
+	 * per the unified-video-pipeline PRD; the third of the trio beside <VideoPlayer>
+	 * and <Flythrough>.
+	 *
+	 * A `collection.json` is several cuts of the SAME demo (a 30s teaser, a 2min
+	 * walkthrough, an audience-specific edit). The host hands the parsed manifest;
+	 * this component owns the "which cut" selection and delegates playback to
+	 * <VideoPlayer> — so a cut gets the full player (aspect-lock, poster, captions,
+	 * keyboard) for free, and this file only adds the picker.
+	 *
+	 * Contract: takes only decode-checked assets already referenced by the manifest
+	 * (each cut's `url` + `poster`). No fetching, no ffmpeg — the manifest is the
+	 * input, exactly as `demo-assemble` emitted it.
+	 */
+	import VideoPlayer from './VideoPlayer.svelte';
+	// Collection / CollectionCut are declared in the `module` script above and are
+	// already in scope here — no import (that would conflict with the local decl).
+
+	let {
+		collection,
+		cut = null,
+		aspect = '16:9',
+		class: className = ''
+	}: {
+		collection: Collection;
+		/** Preselect a cut by `id`. Falls back to the first cut. */
+		cut?: string | null;
+		/** Aspect passed through to the inner <VideoPlayer>. */
+		aspect?: string | null;
+		class?: string;
+	} = $props();
+
+	const cuts = $derived(
+		Array.isArray(collection?.cuts)
+			? collection.cuts.filter((c): c is CollectionCut => !!c && typeof c.url === 'string')
+			: []
+	);
+
+	// Selected cut id. Seeded from `cut` when it names a real cut, else the first.
+	// `$state` initialiser reads props once; a later `cut` change is reconciled by
+	// the effect below rather than re-running the initialiser.
+	let selectedId = $state<string | null>(null);
+	$effect(() => {
+		const ids = cuts.map((c) => c.id);
+		const wanted = cut && ids.includes(cut) ? cut : null;
+		// Only (re)seed when the current selection is gone or a valid `cut` arrives.
+		if (selectedId == null || !ids.includes(selectedId)) {
+			selectedId = wanted ?? ids[0] ?? null;
+		} else if (wanted && wanted !== selectedId && cut === wanted) {
+			// Host explicitly asked for a different cut via the prop.
+			selectedId = wanted;
+		}
+	});
+
+	const active = $derived(cuts.find((c) => c.id === selectedId) ?? cuts[0] ?? null);
+
+	function fmtDuration(s: number | undefined): string {
+		if (!Number.isFinite(s) || (s ?? 0) <= 0) return '';
+		const total = Math.round(s as number);
+		const m = Math.floor(total / 60);
+		const sec = total % 60;
+		return m > 0 ? `${m}:${String(sec).padStart(2, '0')}` : `${sec}s`;
+	}
+
+	function poster(c: CollectionCut): string | undefined {
+		return c.poster_url ?? c.poster ?? undefined;
+	}
+</script>
+
+<div class="le-root {className}">
+	{#if cuts.length === 0}
+		<div class="le-empty">No cuts in this collection.</div>
+	{:else}
+		{#if cuts.length > 1}
+			<!-- Cut picker: a tab row. Each cut is one edit of the same demo, so the
+			     picker reads as "which version", not "which video". -->
+			<div class="le-picker" role="tablist" aria-label="Demo cuts">
+				{#each cuts as c (c.id)}
+					<button
+						type="button"
+						role="tab"
+						class="le-tab"
+						class:active={c.id === selectedId}
+						aria-selected={c.id === selectedId}
+						onclick={() => (selectedId = c.id)}
+					>
+						<span class="le-tab-label">{c.label ?? c.id}</span>
+						{#if fmtDuration(c.duration_sec)}
+							<span class="le-tab-dur">{fmtDuration(c.duration_sec)}</span>
+						{/if}
+						{#if c.blurb}<span class="le-tab-blurb">{c.blurb}</span>{/if}
+					</button>
+				{/each}
+			</div>
+		{/if}
+
+		{#if active}
+			<!-- keyed so switching cuts remounts the player (a fresh source + poster,
+			     not a src swap mid-playback). -->
+			{#key active.id}
+				<VideoPlayer src={active.url} poster={poster(active)} {aspect} />
+			{/key}
+		{/if}
+	{/if}
+</div>
+
+<style>
+	.le-root {
+		display: flex;
+		flex-direction: column;
+		gap: var(--jatui-space-lg, 12px);
+		min-width: 0;
+	}
+
+	.le-empty {
+		padding: var(--jatui-space-xl, 16px);
+		text-align: center;
+		color: color-mix(in oklch, var(--color-base-content) 60%, transparent);
+		background: var(--color-base-200);
+		border-radius: var(--jatui-radius-box, 0.5rem);
+		font-size: 0.85rem;
+	}
+
+	.le-picker {
+		display: flex;
+		flex-wrap: wrap;
+		gap: var(--jatui-space-sm, 4px);
+	}
+
+	.le-tab {
+		display: flex;
+		flex-direction: column;
+		align-items: flex-start;
+		gap: var(--jatui-space-xs, 2px);
+		padding: var(--jatui-space-sm, 4px) var(--jatui-space-lg, 12px);
+		background: color-mix(in oklch, var(--color-base-content) 6%, transparent);
+		border: var(--jatui-border-w, 1px) solid transparent;
+		border-radius: var(--jatui-radius-selector, 0.375rem);
+		color: var(--color-base-content);
+		text-align: left;
+		cursor: pointer;
+		transition:
+			background var(--motion-fast, 150ms) var(--motion-glide, ease-out),
+			border-color var(--motion-fast, 150ms) var(--motion-glide, ease-out);
+	}
+
+	.le-tab:hover {
+		background: color-mix(in oklch, var(--color-base-content) 12%, transparent);
+	}
+
+	.le-tab.active {
+		background: color-mix(in oklch, var(--color-primary) 12%, transparent);
+		border-color: var(--color-primary);
+	}
+
+	.le-tab-label {
+		font-size: 0.8rem;
+		font-weight: 600;
+	}
+
+	.le-tab-dur {
+		font-size: 0.66rem;
+		font-variant-numeric: tabular-nums;
+		color: color-mix(in oklch, var(--color-base-content) 55%, transparent);
+	}
+
+	.le-tab-blurb {
+		font-size: 0.7rem;
+		color: color-mix(in oklch, var(--color-base-content) 70%, transparent);
+		max-width: 16rem;
+	}
+
+	@media (prefers-reduced-motion: reduce) {
+		.le-tab {
+			transition: none;
+		}
+	}
+</style>

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

@@ -0,0 +1,47 @@
+/**
+ * The demo-assemble `collection.json` shape (pinned from mardukos
+ * `scripts/demo-assemble.mjs` writer + `welcome/[token]` reader, per
+ * docs/edl-contract.md). Fields the writer emits with `_url` suffixes are
+ * accepted alongside the reader's shorter aliases, so a manifest from either
+ * side of the contract loads without a translation step.
+ */
+/** One beat's timing within a cut (for a future chapter rail; carried through). */
+export interface CollectionBeat {
+    id: string | number;
+    name?: string;
+    start_sec?: number;
+    end_sec?: number;
+}
+/** A named output variant — one playable video. */
+export interface CollectionCut {
+    id: string;
+    label?: string;
+    /** Assemble writes `blurb`; audience copy for the picker. */
+    blurb?: string;
+    duration_sec?: number;
+    /** The mp4. Writer/reader both use `url` (minio or repo-relative path). */
+    url: string;
+    /** Cover art. Writer emits `poster_url`; `poster` accepted as an alias. */
+    poster_url?: string;
+    poster?: string;
+    beats?: CollectionBeat[];
+}
+/** The `collection.json` manifest. */
+export interface Collection {
+    template?: string;
+    prospect?: string | null;
+    brand_name?: string;
+    primary_color?: string;
+    cuts: CollectionCut[];
+}
+type $$ComponentProps = {
+    collection: Collection;
+    /** Preselect a cut by `id`. Falls back to the first cut. */
+    cut?: string | null;
+    /** Aspect passed through to the inner <VideoPlayer>. */
+    aspect?: string | null;
+    class?: string;
+};
+declare const LessonEmbed: import("svelte").Component<$$ComponentProps, {}, "">;
+type LessonEmbed = ReturnType<typeof LessonEmbed>;
+export default LessonEmbed;

package/dist/components/MediaWorkbench.svelte

@@ -95,9 +95,10 @@
      * Identifies the existing asset-store row being edited, if any. Forwarded
      * to /api/media/edit and /api/media/remove-bg so the host app's
      * kind='record' safety check (assets that must never be AI pixel-edited)
-     * can run server-side. Omit for generate-only or non-asset-store usage —
-     * the check is skipped entirely when absent, matching every call site
-     * that predates this prop.
+     * can run server-side. Safe to omit for a genuinely untracked image
+     * (freshly generated, not yet saved) — a host that fail-closes this
+     * check (as mardukos does) derives the id from the source URL instead
+     * when it's absent, so this is a convenience, not the only signal.
      */
     assetId?: string
   }>()
@@ -390,6 +391,7 @@
       const fd = new FormData()
       fd.append("image", blob, "source.png")
       if (assetId) fd.append("assetId", assetId)
+      fd.append("sourceUrl", sourceUrl)
       const res = await fetch("/api/media/remove-bg", { method: "POST", body: fd })
       if (!res.ok) {
         const msg = await res.text().catch(() => res.statusText)

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

@@ -7,9 +7,10 @@ type $$ComponentProps = {
      * Identifies the existing asset-store row being edited, if any. Forwarded
      * to /api/media/edit and /api/media/remove-bg so the host app's
      * kind='record' safety check (assets that must never be AI pixel-edited)
-     * can run server-side. Omit for generate-only or non-asset-store usage —
-     * the check is skipped entirely when absent, matching every call site
-     * that predates this prop.
+     * can run server-side. Safe to omit for a genuinely untracked image
+     * (freshly generated, not yet saved) — a host that fail-closes this
+     * check (as mardukos does) derives the id from the source URL instead
+     * when it's absent, so this is a convenience, not the only signal.
      */
     assetId?: string;
 };

package/dist/components/VideoPlayer.svelte

@@ -116,9 +116,13 @@
 	let {
 		src,
 		poster = null,
+		aspect = '16:9',
+		autoplay = false,
+		loop = false,
 		captionsSrc = null,
 		captionsLabel = 'Captions',
 		captionsLang = 'en',
+		captionsDefault = true,
 		chapters = [],
 		speakers = [],
 		transcript = [],
@@ -135,9 +139,42 @@
 	}: {
 		src: string;
 		poster?: string | null;
+		/**
+		 * Aspect ratio for the video stage — presentation-primitive prop (PRD).
+		 * `"16:9"` | `"4:3"` | `"1:1"` | `"9:16"` | `"21:9"`, a bare number ratio
+		 * (`"1.85"`), or `null`/`"auto"` to let the video's own intrinsic ratio drive
+		 * the box. The stage reserves this ratio from the first frame so poster →
+		 * video swap never shoves layout (the poster convention: cover art fills the
+		 * locked box until the first decoded frame paints over it).
+		 */
+		aspect?: string | null;
+		/**
+		 * Autoplay muted on mount — presentation-primitive prop (PRD). Honoured only
+		 * when the user has NOT asked to reduce motion; under `prefers-reduced-motion`
+		 * the video stays paused on its poster (autoplaying video is motion). Autoplay
+		 * forces `muted` regardless (browsers block unmuted autoplay).
+		 */
+		autoplay?: boolean;
+		/** Loop playback — presentation-primitive prop (PRD). */
+		loop?: boolean;
 		captionsSrc?: string | null;
 		captionsLabel?: string;
 		captionsLang?: string;
+		/**
+		 * Should the captions <track> start ENABLED (`default` attribute)?
+		 *
+		 * `true` (default) preserves the historical behaviour: a track with a src
+		 * shows on load. Pass `false` when the video already has captions burned
+		 * into its frames (e.g. an academy episode render) — the track is still
+		 * present and toggleable from the native menu, but not painted on top of
+		 * the burned-in text, which would double every caption.
+		 *
+		 * Long-term direction (see the double-caption bug, jat-abwim): renders
+		 * should STOP burning captions into the frames and rely on this
+		 * toggleable VTT track alone. Until episodes are re-rendered without
+		 * burned-in text, a burned-in episode passes `captionsDefault={false}`.
+		 */
+		captionsDefault?: boolean;
 		chapters?: VideoChapter[];
 		speakers?: VideoSpeakerTurn[];
 		transcript?: VideoTranscriptSegment[];
@@ -161,6 +198,37 @@
 		class?: string;
 	} = $props();
 
+	/**
+	 * `aspect` → a CSS `aspect-ratio` value. Accepts `"W:H"`, a bare ratio number,
+	 * or null/"auto" (⇒ no lock; the video's intrinsic ratio drives the box). Shared
+	 * with <Flythrough>/<LessonEmbed> conceptually, kept inline so the primitive has
+	 * no cross-file coupling for one small pure function.
+	 */
+	const aspectRatioCss = $derived.by(() => {
+		const a = aspect;
+		if (a == null) return null;
+		const trimmed = String(a).trim();
+		if (trimmed === '' || trimmed === 'auto') return null;
+		const colon = trimmed.match(/^(\d+(?:\.\d+)?)\s*[:/]\s*(\d+(?:\.\d+)?)$/);
+		if (colon) {
+			const w = parseFloat(colon[1]);
+			const h = parseFloat(colon[2]);
+			if (w > 0 && h > 0) return `${w} / ${h}`;
+		}
+		const num = Number(trimmed);
+		if (Number.isFinite(num) && num > 0) return String(num);
+		return null;
+	});
+
+	// prefers-reduced-motion gate for autoplay: an autoplaying clip IS motion, so
+	// under the reduce preference the video holds on its poster instead. Tracked
+	// live (media query listener) so a mid-session preference flip is honoured, and
+	// SSR-safe (matchMedia only exists in the browser; defaults to "not reduced").
+	let reduceMotion = $state(false);
+	// Autoplay forces muted — browsers refuse to autoplay audible video, and a
+	// silent presentation clip is the point of the primitive anyway.
+	const effectiveAutoplay = $derived(autoplay && !reduceMotion);
+
 	// ── Element refs + media state ──────────────────────────────────────────
 	let videoEl: HTMLVideoElement | undefined = $state();
 	let canvasEl: HTMLCanvasElement | undefined = $state();
@@ -675,13 +743,49 @@
 			clearColorCache();
 			themeTick++;
 		});
+
+		// Live reduced-motion tracking — drives the autoplay gate. A flip toward
+		// "reduce" mid-playback pauses the clip on its current frame; a flip away
+		// lets a queued autoplay fire (the effect below owns actually starting it).
+		let stopReduce: (() => void) | undefined;
+		if (typeof window !== 'undefined' && window.matchMedia) {
+			const mq = window.matchMedia('(prefers-reduced-motion: reduce)');
+			reduceMotion = mq.matches;
+			const onChange = () => (reduceMotion = mq.matches);
+			mq.addEventListener('change', onChange);
+			stopReduce = () => mq.removeEventListener('change', onChange);
+		}
+
 		return () => {
 			stopTheme();
+			stopReduce?.();
 			if (zoomTimer) clearTimeout(zoomTimer);
 			if (osdTimer) clearTimeout(osdTimer);
 		};
 	});
 
+	// Autoplay is applied imperatively (a queued `.play()` that the reduced-motion
+	// gate can veto) rather than via the native `autoplay` attribute, so a
+	// mid-session preference flip is respected instead of being a mount-only
+	// decision. The `.play()` promise can reject (no user gesture, tab backgrounded)
+	// — that's fine, the poster stays and the controls remain.
+	let didAutoplay = false;
+	$effect(() => {
+		const v = videoEl;
+		const go = effectiveAutoplay;
+		untrack(() => {
+			if (!v) return;
+			if (go && !didAutoplay) {
+				didAutoplay = true;
+				v.muted = true;
+				void v.play().catch(() => {});
+			} else if (!go && reduceMotion && didAutoplay && !v.paused) {
+				// Preference flipped to reduce after we'd started — settle on a frame.
+				v.pause();
+			}
+		});
+	});
+
 	// ── Band pointer handlers ───────────────────────────────────────────────
 	function canvasSec(e: MouseEvent): { sec: number; x: number; width: number } | null {
 		const canvas = canvasEl;
@@ -943,7 +1047,12 @@
 >
 	<div class="vp-main">
 		<!-- svelte-ignore a11y_no_static_element_interactions -->
-		<div class="vp-stage" onwheel={onStageWheel}>
+		<div
+			class="vp-stage"
+			class:vp-stage-locked={aspectRatioCss != null}
+			style={aspectRatioCss != null ? `--vp-aspect: ${aspectRatioCss};` : undefined}
+			onwheel={onStageWheel}
+		>
 			<video
 				bind:this={videoEl}
 				bind:currentTime
@@ -951,13 +1060,20 @@
 				ontimeupdate={handleTimeUpdate}
 				onloadedmetadata={onLoadedMetadata}
 				{src}
+				{loop}
+				muted={effectiveAutoplay || undefined}
 				poster={poster ?? undefined}
 				controls
+				playsinline
 				class="vp-video"
 			>
 				<!-- A captions track is always present for a11y; without a src it is
-				     an empty, inert track rather than a missing affordance. -->
-				<track kind="captions" src={captionsSrc ?? undefined} srclang={captionsLang} label={captionsLabel} default={!!captionsSrc} />
+				     an empty, inert track rather than a missing affordance. It starts
+				     ENABLED only when there's a src AND the host opts in via
+				     captionsDefault (true by default). A burned-in-captions video
+				     passes captionsDefault={false} so the track stays available in the
+				     menu but isn't painted on top of the frames' own text (jat-abwim). -->
+				<track kind="captions" src={captionsSrc ?? undefined} srclang={captionsLang} label={captionsLabel} default={!!captionsSrc && captionsDefault} />
 			</video>
 			<div class="vp-osd" class:on={osdOn} aria-hidden="true">{osd}</div>
 		</div>
@@ -1202,6 +1318,27 @@
 		position: relative;
 	}
 
+	/* Aspect-lock: the stage reserves --vp-aspect from the first frame, so the
+	   poster → decoded-video swap never resizes the box (the poster convention).
+	   The video is absolutely filled into the locked box with object-fit: contain,
+	   so a source whose intrinsic ratio differs letterboxes instead of stretching. */
+	.vp-stage-locked {
+		aspect-ratio: var(--vp-aspect);
+		width: 100%;
+		background: var(--color-neutral);
+		border-radius: var(--jatui-radius-field, 0.25rem);
+		overflow: hidden;
+	}
+
+	.vp-stage-locked .vp-video {
+		position: absolute;
+		inset: 0;
+		width: 100%;
+		height: 100%;
+		object-fit: contain;
+		border-radius: 0;
+	}
+
 	.vp-video {
 		display: block;
 		width: 100%;

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

@@ -47,9 +47,42 @@ export interface VideoSpeakerTalkTime {
 type $$ComponentProps = {
     src: string;
     poster?: string | null;
+    /**
+     * Aspect ratio for the video stage — presentation-primitive prop (PRD).
+     * `"16:9"` | `"4:3"` | `"1:1"` | `"9:16"` | `"21:9"`, a bare number ratio
+     * (`"1.85"`), or `null`/`"auto"` to let the video's own intrinsic ratio drive
+     * the box. The stage reserves this ratio from the first frame so poster →
+     * video swap never shoves layout (the poster convention: cover art fills the
+     * locked box until the first decoded frame paints over it).
+     */
+    aspect?: string | null;
+    /**
+     * Autoplay muted on mount — presentation-primitive prop (PRD). Honoured only
+     * when the user has NOT asked to reduce motion; under `prefers-reduced-motion`
+     * the video stays paused on its poster (autoplaying video is motion). Autoplay
+     * forces `muted` regardless (browsers block unmuted autoplay).
+     */
+    autoplay?: boolean;
+    /** Loop playback — presentation-primitive prop (PRD). */
+    loop?: boolean;
     captionsSrc?: string | null;
     captionsLabel?: string;
     captionsLang?: string;
+    /**
+     * Should the captions <track> start ENABLED (`default` attribute)?
+     *
+     * `true` (default) preserves the historical behaviour: a track with a src
+     * shows on load. Pass `false` when the video already has captions burned
+     * into its frames (e.g. an academy episode render) — the track is still
+     * present and toggleable from the native menu, but not painted on top of
+     * the burned-in text, which would double every caption.
+     *
+     * Long-term direction (see the double-caption bug, jat-abwim): renders
+     * should STOP burning captions into the frames and rely on this
+     * toggleable VTT track alone. Until episodes are re-rendered without
+     * burned-in text, a burned-in episode passes `captionsDefault={false}`.
+     */
+    captionsDefault?: boolean;
     chapters?: VideoChapter[];
     speakers?: VideoSpeakerTurn[];
     transcript?: VideoTranscriptSegment[];

package/dist/index.d.ts

@@ -13,6 +13,9 @@ export { default as TranscriptPlayer } from './components/TranscriptPlayer.svelt
 export type { TranscriptSegment, TranscriptBookmark, TranscriptChapter, TranscriptSpeakerTalkTime, } from './components/TranscriptPlayer.svelte';
 export { default as VideoPlayer } from './components/VideoPlayer.svelte';
 export type { VideoChapter, VideoSpeakerTurn, VideoTranscriptSegment, VideoBookmark, VideoWaveform, VideoSpeakerTalkTime, } from './components/VideoPlayer.svelte';
+export { default as Flythrough } from './components/Flythrough.svelte';
+export { default as LessonEmbed } from './components/LessonEmbed.svelte';
+export type { Collection, CollectionCut, CollectionBeat, } from './components/LessonEmbed.svelte';
 export { buildLinkedSession, buildLinkedSessionFromWork, rawTypeToState, sampleLinkedSession, SAMPLE_TRANSCRIPT_LINES, } from './components/session-nav/transcriptModel';
 export type { ItemKind, TranscriptItem, FileTouchedEntry, SignalNode, LinkedSession, WorkBlockClient, WorkTranscriptItemClient, } from './components/session-nav/transcriptModel';
 export { default as UserAvatar } from './components/UserAvatar.svelte';

package/dist/index.js

@@ -13,6 +13,13 @@ export { default as TranscriptPlayer } from './components/TranscriptPlayer.svelt
 // optional so a bare mp4 still gets the full playback UX. TranscriptPlayer
 // stays exported unchanged — meetings already depends on it.
 export { default as VideoPlayer } from './components/VideoPlayer.svelte';
+// Presentation-primitive video trio (unified-video-pipeline PRD): the frozen
+// surface academy + mardukos consume. VideoPlayer (above) doubles as the full
+// player AND the presentation player — extended with aspect/autoplay/loop +
+// aspect-lock + reduced-motion; Flythrough is the ambient motion embed; and
+// LessonEmbed renders a demo-assemble collection.json (cut picker + player).
+export { default as Flythrough } from './components/Flythrough.svelte';
+export { default as LessonEmbed } from './components/LessonEmbed.svelte';
 // Data models — Session transcript (from JAT IDE, jat-jj79f.16 G1)
 export { buildLinkedSession, buildLinkedSessionFromWork, rawTypeToState, sampleLinkedSession, SAMPLE_TRANSCRIPT_LINES, } from './components/session-nav/transcriptModel';
 // Components — Universal

package/package.json

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