@joewinke/jatui 0.2.29 → 0.2.31

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

@@ -85,11 +85,22 @@
     uploadEndpoint = "/api/media",
     onComplete = undefined,
     accept = "image/png,image/jpeg,image/webp,image/gif",
+    assetId = undefined,
   } = $props<{
     value?: string | null
     uploadEndpoint?: string
     onComplete?: (url: string) => void
     accept?: string
+    /**
+     * 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. 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
   }>()
 
   let open = $state(false)
@@ -355,7 +366,7 @@
       const res = await fetch("/api/media/edit", {
         method: "POST",
         headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ imageUrl: sourceUrl, instruction: editInstruction }),
+        body: JSON.stringify({ imageUrl: sourceUrl, instruction: editInstruction, assetId }),
       })
       const body = await res.json().catch(() => ({})) as { error?: string; url?: string }
       if (!res.ok) throw new Error(body.error ?? `HTTP ${res.status}`)
@@ -379,6 +390,8 @@
       const blob = await imgRes.blob()
       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

@@ -3,6 +3,16 @@ type $$ComponentProps = {
     uploadEndpoint?: string;
     onComplete?: (url: string) => void;
     accept?: string;
+    /**
+     * 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. 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;
 };
 declare const MediaWorkbench: import("svelte").Component<$$ComponentProps, {}, "value">;
 type MediaWorkbench = ReturnType<typeof MediaWorkbench>;

package/dist/components/VideoPlayer.svelte

@@ -116,6 +116,9 @@
 	let {
 		src,
 		poster = null,
+		aspect = '16:9',
+		autoplay = false,
+		loop = false,
 		captionsSrc = null,
 		captionsLabel = 'Captions',
 		captionsLang = 'en',
@@ -135,6 +138,24 @@
 	}: {
 		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;
@@ -161,6 +182,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 +727,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 +1031,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,8 +1044,11 @@
 				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
@@ -1202,6 +1298,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,6 +47,24 @@ 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;

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.29",
+  "version": "0.2.31",
   "private": false,
   "description": "Shared Svelte 5 component library for JAT projects",
   "type": "module",