@joewinke/jatui 0.46.0 → 0.48.0

package/dist/ambience/types.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Ambience engine — public types. The scape contract lives here so the
+ * parallel scape tasks build against it without importing the engine.
+ *
+ * Design rules (jatui-km0qy): headless — no UI, no window at import, one
+ * AudioContext per engine created lazily on the first gesture-driven play,
+ * generative Web Audio only (no files, no libraries).
+ */
+/** A node scapes connect INTO; the shared master chain owns what happens after. */
+export interface ScapeContext {
+    /** The engine's single AudioContext (created lazily, already running). */
+    audio: AudioContext;
+    /** Connect your scape's output(s) here — never to `destination` directly. */
+    input: AudioNode;
+    /** The one shared breath LFO (see breath.ts). */
+    breath: BreathClock;
+    /** Lookahead scheduler: call `cb` on every engine tick (~250 ms). Registering
+     *  returns an unsubscribe so a scape can stop being ticked on stop(). */
+    lookahead: (cb: (now: number) => void) => () => void;
+    /** Deterministic-ish random source scoped to the scape instance. */
+    rand: () => number;
+}
+export interface ScapeInstance {
+    /** Begin sounding at audio time `at` (usually ctx.currentTime). */
+    start(at: number): void;
+    /** Fade yourself out over `fade` seconds and tear your own nodes down. */
+    stop(at: number, fade: number): void;
+    /** Optional live parameter (scape-defined keys). */
+    setParam?(key: string, value: number): void;
+}
+export type ScapeGroup = 'meditation' | 'focus' | 'noise' | 'nature' | 'music';
+export interface Scape {
+    id: string;
+    label: string;
+    group: ScapeGroup;
+    description?: string;
+    /** Build the graph. Called once per play — a scape must be re-buildable. */
+    build(ctx: ScapeContext): ScapeInstance;
+}
+/** Shape of the AudioContext we need — the real one satisfies it; tests fake it. */
+import type { BreathClock } from './breath';
+export type AudioContextLike = AudioContext;
+export interface AmbienceState {
+    /** Currently selected scape id (persisted preselect counts), or null. */
+    currentId: string | null;
+    playing: boolean;
+    volume: number;
+}
+export interface BreathState {
+    /** 0..1 within the current half-breath (inhale or exhale). */
+    value: number;
+    /** True while inhaling. */
+    rising: boolean;
+}
+export interface Ambience {
+    register(scape: Scape): void;
+    list(): Scape[];
+    /** MUST be called from a user gesture (a click/keydown handler). Rejects
+     *  otherwise. Resolves once the scape is scheduled and audibly started. */
+    play(id: string): Promise<void>;
+    /** Fade out ~0.55 s; the AudioContext closes ~3 s later. A play() inside
+     *  that window cancels the close and fades back in over ~4 s. */
+    stop(): void;
+    /** Immediate: no fades, context closed, timers cleared. */
+    kill(): void;
+    setVolume(v: number): void;
+    get state(): AmbienceState;
+    subscribe(fn: (state: AmbienceState) => void): () => void;
+    onBreath(fn: (b: BreathState) => void): () => void;
+}
+export interface AmbienceOptions {
+    storageKey?: string;
+    defaultVolume?: number;
+    /** Gesture probe, injectable for tests. Default: navigator.userActivation
+     * when it exists (trusted-UI truth), otherwise permissive (SSR/node).
+     */
+    isGesture?: () => boolean;
+    /** Context factory, injectable for tests (default: `new AudioContext()`). */
+    createContext?: () => AudioContextLike;
+}

package/dist/ambience/types.js

@@ -0,0 +1,9 @@
+/**
+ * Ambience engine — public types. The scape contract lives here so the
+ * parallel scape tasks build against it without importing the engine.
+ *
+ * Design rules (jatui-km0qy): headless — no UI, no window at import, one
+ * AudioContext per engine created lazily on the first gesture-driven play,
+ * generative Web Audio only (no files, no libraries).
+ */
+export {};

package/dist/components/AmbienceToggle.svelte

@@ -0,0 +1,599 @@
+<script module lang="ts">
+	/**
+	 * AmbienceToggle — the audio twin of ThemeToggle (jatui-b7qvr): one small
+	 * speaker button for the app shell over the headless ambience engine
+	 * (`createAmbience()` from `src/lib/ambience/`).
+	 *
+	 * Interaction contract:
+	 *   - Click (or Space/Enter) = play / stop the last scape. A gesture-gated
+	 *     engine call, made synchronously inside the click handler.
+	 *   - The scape menu (menu button pattern) opens with ArrowDown/ArrowUp,
+	 *     a press-and-hold (~450 ms) or a right-click (Android/Chrome fire
+	 *     contextmenu on touch holds; iOS may cancel the pointer instead —
+	 *     the keyboard path always works). It lists every
+	 *     registered scape grouped meditation / focus / noise / nature / music
+	 *     (`menuitemradio` items, current scape checked), carries a volume
+	 *     slider wired to `engine.setVolume`, and shows each scape's
+	 *     `description` as its secondary line — playlist scapes put their
+	 *     track attribution there.
+	 *
+	 * A11y: the trigger is `aria-pressed` while playing and carries the full
+	 * menu-button wiring (`aria-expanded` / `aria-haspopup` / `aria-controls`).
+	 * An sr-only description teaches the menu gestures, and an `aria-live`
+	 * status line announces state changes ("Ambience: Hibiscus, playing").
+	 * The speaker glyph morphs off↔on on the motion tokens and, while playing,
+	 * breathes with `engine.onBreath` — ambient motion, so it is static under
+	 * `prefers-reduced-motion` and `data-motion="calm"`.
+	 *
+	 * Token-only theming (DaisyUI + `--jatui-*` + `--motion-*`). SSR-safe: the
+	 * engine is lazy and nothing here touches `window` at import.
+	 */
+	import type { Ambience, Scape, ScapeGroup } from '../ambience/types';
+
+	/** Canonical menu group order (the Scape contract's groups). */
+	export const AMBIENCE_GROUP_ORDER: readonly ScapeGroup[] = [
+		'meditation',
+		'focus',
+		'noise',
+		'nature',
+		'music'
+	];
+
+	/** Human labels for the canonical groups. */
+	export const GROUP_LABELS: Readonly<Record<ScapeGroup, string>> = {
+		meditation: 'Meditation',
+		focus: 'Focus',
+		noise: 'Noise',
+		nature: 'Nature',
+		music: 'Music'
+	};
+
+	/** One grouped section of the scape menu. */
+	export interface AmbienceScapeGroup {
+		group: ScapeGroup;
+		label: string;
+		scapes: Scape[];
+	}
+
+	/**
+	 * Group scapes for the menu: canonical group order, registration order
+	 * within a group, empty groups omitted. A group outside the union (a
+	 * registry from a newer engine) still renders, after the known ones, in
+	 * first-seen order — a menu never silently drops a registered scape.
+	 */
+	export function groupScapes(scapes: Scape[]): AmbienceScapeGroup[] {
+		const byGroup = new Map<string, Scape[]>();
+		for (const s of scapes) {
+			const list = byGroup.get(s.group) ?? [];
+			list.push(s);
+			byGroup.set(s.group, list);
+		}
+		const out: AmbienceScapeGroup[] = [];
+		for (const g of AMBIENCE_GROUP_ORDER) {
+			const list = byGroup.get(g);
+			if (!list?.length) continue;
+			out.push({ group: g, label: GROUP_LABELS[g], scapes: list });
+			byGroup.delete(g);
+		}
+		for (const [g, list] of byGroup) {
+			const label = g ? g.charAt(0).toUpperCase() + g.slice(1) : 'Other';
+			out.push({ group: g as ScapeGroup, label, scapes: list });
+		}
+		return out;
+	}
+
+	/**
+	 * The live label — "Ambience: Hibiscus, playing" while sounding,
+	 * "Ambience: Hibiscus, stopped" once a scape has been selected but is not
+	 * playing, "Ambience: off" before anything was selected.
+	 */
+	export function ambienceLiveLabel(currentLabel: string | null, playing: boolean): string {
+		if (!currentLabel) return 'Ambience: off';
+		return `Ambience: ${currentLabel}, ${playing ? 'playing' : 'stopped'}`;
+	}
+
+	/** Transient failure label — a rejected engine.play() (gesture probe,
+	 * context suspend, unknown scape) must never surface as an unhandled
+	 * rejection OR as silence: the trigger visibly fails to respond, so the
+	 * sr-only status explains it. Cleared by the next successful play. */
+	export const PLAY_ERROR_LABEL = 'Ambience: couldn\'t start — tap again';
+
+	/**
+	 * Glyph scale for a breath value (0..1): the speaker grows on the inhale
+	 * and settles on the exhale — 6% total, clamped against out-of-range input.
+	 */
+	export function breathScale(value: number): number {
+		const v = Math.min(1, Math.max(0, value));
+		return 1 + 0.06 * v;
+	}
+</script>
+
+<script lang="ts">
+	import { getMotionContext } from '../motion/level';
+
+	let {
+		engine,
+		compact = false,
+		placement = 'bottom-end'
+	}: {
+		/** The engine instance (from `createAmbience()`). The component never creates one, and never kills it — the host owns the engine's lifecycle. */
+		engine: Ambience;
+		/** Smaller app-shell footprint: 40px trigger with an 18px glyph (default 44px / 20px). Never below the 40px touch floor. */
+		compact?: boolean;
+		/** Which way the menu opens from the trigger. Auto-flips vertically when the viewport has no room on that side. */
+		placement?: 'bottom-start' | 'bottom-end' | 'top-start' | 'top-end';
+	} = $props();
+
+	const menuId = $props.id();
+	const hintId = `${menuId}-hint`;
+
+	/** Long-press duration for the pointer path to the menu. */
+	const LONG_PRESS_MS = 450;
+	/** Worst-case menu height used for the open-direction flip decision. */
+	const MENU_EST_HEIGHT = 340;
+
+	let playing = $state(false);
+	let currentId = $state<string | null>(null);
+	let volume = $state(0.6);
+	let scapes = $state<Scape[]>([]);
+	let open = $state(false);
+	// svelte-ignore state_referenced_locally -- only the seed; resolvePlacement() reads the live prop
+	let effectivePlacement = $state<'bottom-start' | 'bottom-end' | 'top-start' | 'top-end'>(
+		placement
+	);
+
+	/** Set by a long-press so the click that follows the release is swallowed —
+	 *  but only the mouse click (detail > 0), never a keyboard activation. */
+	let longPressed = false;
+	let pressTimer: ReturnType<typeof setTimeout> | null = null;
+	let pressStart: { x: number; y: number } | null = null;
+
+	let btnRef = $state<HTMLButtonElement | null>(null);
+	let panelRef = $state<HTMLDivElement | null>(null);
+	let glyphRef = $state<HTMLSpanElement | null>(null);
+
+	let playError = $state(false);
+
+	const currentScape = $derived(scapes.find((s) => s.id === currentId) ?? null);
+	const currentLabel = $derived(currentScape?.label ?? currentId);
+	const groups = $derived(groupScapes(scapes));
+	const liveLabel = $derived(
+		playError ? PLAY_ERROR_LABEL : ambienceLiveLabel(currentLabel, playing)
+	);
+	const disabled = $derived(scapes.length === 0);
+	const sliderValue = $derived(Math.round(volume * 100));
+
+	const BUTTON_SIZE = $derived(compact ? 'size-10' : 'size-11');
+	const ICON_SIZE = $derived(compact ? 18 : 20);
+
+	// Engine state → component state. subscribe() fires once immediately, so
+	// this also fills the initial (persisted-preselect) state at mount.
+	$effect(() => {
+		return engine.subscribe((s) => {
+			playing = s.playing;
+			currentId = s.currentId;
+			volume = s.volume;
+			scapes = engine.list();
+			// A successful play (state flips to playing) clears the failure.
+			if (s.playing) playError = false;
+		});
+	});
+
+	// Breathing glyph: follow the engine's shared breath clock while playing,
+	// and only where ambient motion is allowed (getMotionContext().ambient is
+	// false under prefers-reduced-motion AND under data-motion="calm"). The
+	// value lands in a CSS variable the stylesheet turns into a smoothed
+	// scale — the callbacks run at the engine's ~4 Hz tick, the transition
+	// interpolates between them.
+	$effect(() => {
+		if (!playing) return;
+		if (!getMotionContext(btnRef).ambient) return;
+		const glyph = glyphRef;
+		if (!glyph) return;
+		const off = engine.onBreath((b) => {
+			glyph.style.setProperty('--jatui-ambience-breath', String(breathScale(b.value)));
+		});
+		return () => {
+			off();
+			// Drop the frozen scale so the stopped glyph sits at rest.
+			glyph.style.removeProperty('--jatui-ambience-breath');
+		};
+	});
+
+	// While open: click-outside dismissal (capture phase, so a press that
+	// begins outside never reaches the page first) and APG focus movement into
+	// the menu — focus the first nav item once the panel exists.
+	$effect(() => {
+		if (!open) return;
+		const panel = panelRef;
+		if (!panel) return;
+		navItems()[0]?.focus();
+		const onDocPointerDown = (e: PointerEvent) => {
+			const t = e.target as Node | null;
+			if (btnRef?.contains(t) || panelRef?.contains(t)) return;
+			closeMenu(false);
+		};
+		document.addEventListener('pointerdown', onDocPointerDown, true);
+		return () => document.removeEventListener('pointerdown', onDocPointerDown, true);
+	});
+
+	function navItems(): HTMLElement[] {
+		return panelRef ? Array.from(panelRef.querySelectorAll<HTMLElement>('[data-ambience-nav]')) : [];
+	}
+
+	function resolvePlacement(): 'bottom-start' | 'bottom-end' | 'top-start' | 'top-end' {
+		const el = btnRef;
+		if (!el || typeof window === 'undefined') return placement;
+		const r = el.getBoundingClientRect();
+		const spaceBelow = window.innerHeight - r.bottom;
+		const spaceAbove = r.top;
+		if (placement.startsWith('bottom') && spaceBelow < MENU_EST_HEIGHT && spaceAbove > spaceBelow)
+			return placement === 'bottom-end' ? 'top-end' : 'top-start';
+		if (placement.startsWith('top') && spaceAbove < MENU_EST_HEIGHT && spaceBelow > spaceAbove)
+			return placement === 'top-end' ? 'bottom-end' : 'bottom-start';
+		return placement;
+	}
+
+	function openMenu() {
+		if (disabled) return;
+		scapes = engine.list(); // freshest registry snapshot for the menu
+		effectivePlacement = resolvePlacement();
+		open = true;
+	}
+
+	function closeMenu(refocus = true) {
+		if (!open) return;
+		open = false;
+		if (refocus) btnRef?.focus();
+	}
+
+	function togglePlay(e: MouseEvent) {
+		// A long-press already opened the menu — don't also fire the toggle
+		// (keyboard activations, detail 0, are never suppressed).
+		if (longPressed && e.detail > 0) {
+			longPressed = false;
+			return;
+		}
+		longPressed = false;
+		if (open) closeMenu(false);
+		if (playing) {
+			engine.stop();
+			return;
+		}
+		const id = engine.state.currentId ?? engine.list()[0]?.id;
+		if (!id) return;
+		attemptPlay(id);
+	}
+
+	/** A rejected engine.play() sets the transient error state (the sr-only
+	 *  status announces it); success clears it. Never an unhandled rejection. */
+	function attemptPlay(id: string) {
+		void engine
+			.play(id)
+			.then(() => {
+				playError = false;
+			})
+			.catch(() => {
+				playError = true;
+			});
+	}
+
+	function selectScape(scape: Scape) {
+		closeMenu(true);
+		// Radio on the already-playing scape is a no-op (no restart crossfade);
+		// the checked-but-stopped scape resumes.
+		if (playing && scape.id === currentId) return;
+		attemptPlay(scape.id);
+	}
+
+	function onVolumeInput(e: Event) {
+		const v = Number((e.currentTarget as HTMLInputElement).value);
+		engine.setVolume(v / 100);
+	}
+
+	// --- pointer path to the menu: press-and-hold ----------------------------
+	function onPointerDown(e: PointerEvent) {
+		longPressed = false;
+		if (e.button !== 0 || disabled) return;
+		pressStart = { x: e.clientX, y: e.clientY };
+		pressTimer = setTimeout(() => {
+			pressTimer = null;
+			longPressed = true;
+			openMenu();
+		}, LONG_PRESS_MS);
+	}
+
+	function clearPress() {
+		if (pressTimer) {
+			clearTimeout(pressTimer);
+			pressTimer = null;
+		}
+		pressStart = null;
+	}
+
+	function onPointerMove(e: PointerEvent) {
+		if (!pressTimer || !pressStart) return;
+		const dx = e.clientX - pressStart.x;
+		const dy = e.clientY - pressStart.y;
+		if (dx * dx + dy * dy > 64) clearPress(); // moved ~8px — a drag, not a hold
+	}
+
+	function onContextMenu(e: MouseEvent) {
+		e.preventDefault();
+		clearPress();
+		openMenu();
+	}
+
+	function onButtonKeydown(e: KeyboardEvent) {
+		if (e.key === 'ArrowDown' || e.key === 'ArrowUp') {
+			e.preventDefault();
+			openMenu();
+		}
+	}
+
+	// --- menu keyboard: APG roving among the nav items -----------------------
+	function onMenuKeydown(e: KeyboardEvent) {
+		if (e.key === 'Escape') {
+			e.preventDefault();
+			closeMenu(true);
+			return;
+		}
+		if (e.key === 'Tab') {
+			// Menus are not tab stops: close and let focus move on.
+			closeMenu(false);
+			return;
+		}
+		// The volume slider owns its own arrows/Home/End.
+		if (e.target instanceof HTMLInputElement) return;
+		if (!['ArrowDown', 'ArrowUp', 'Home', 'End'].includes(e.key)) return;
+		e.preventDefault();
+		const items = navItems();
+		if (!items.length) return;
+		const current = items.indexOf(document.activeElement as HTMLElement);
+		let next: number;
+		if (e.key === 'Home') next = 0;
+		else if (e.key === 'End') next = items.length - 1;
+		else if (current === -1) next = e.key === 'ArrowUp' ? items.length - 1 : 0;
+		else if (e.key === 'ArrowDown') next = (current + 1) % items.length;
+		else next = (current - 1 + items.length) % items.length;
+		items[next]?.focus();
+	}
+
+	const PLACEMENT_CLASS = {
+		'bottom-start': 'top-full left-0 mt-2',
+		'bottom-end': 'top-full right-0 mt-2',
+		'top-start': 'bottom-full left-0 mb-2',
+		'top-end': 'bottom-full right-0 mb-2'
+	} as const;
+</script>
+
+<div class="relative inline-flex shrink-0">
+	<button
+		bind:this={btnRef}
+		type="button"
+		class="jatui-ambience-toggle inline-flex shrink-0 select-none items-center justify-center rounded-full
+			touch-manipulation
+			text-base-content transition-colors duration-[var(--motion-instant,80ms)]
+			focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary
+			hover:bg-base-content/10 focus-visible:bg-base-content/10
+			active:bg-base-content/15 disabled:pointer-events-none disabled:opacity-50
+			{BUTTON_SIZE}"
+		class:is-playing={playing}
+		aria-label={liveLabel}
+		aria-pressed={playing}
+		aria-haspopup="menu"
+		aria-expanded={open}
+		aria-controls={open ? menuId : undefined}
+		aria-describedby={hintId}
+		title={liveLabel}
+		disabled={disabled}
+		onclick={togglePlay}
+		onkeydown={onButtonKeydown}
+		onpointerdown={onPointerDown}
+		onpointerup={clearPress}
+		onpointercancel={clearPress}
+		onpointermove={onPointerMove}
+		onpointerleave={clearPress}
+		oncontextmenu={onContextMenu}
+	>
+		<span
+			bind:this={glyphRef}
+			class="glyphs relative block"
+			style="width: {ICON_SIZE}px; height: {ICON_SIZE}px"
+			aria-hidden="true"
+		>
+			<!-- Stopped: speaker with a strike, lucide volume-x geometry. -->
+			<svg
+				xmlns="http://www.w3.org/2000/svg"
+				viewBox="0 0 24 24"
+				fill="none"
+				stroke="currentColor"
+				stroke-width="2"
+				stroke-linecap="round"
+				stroke-linejoin="round"
+				class="glyph glyph-off absolute inset-0"
+				width={ICON_SIZE}
+				height={ICON_SIZE}
+			>
+				<polygon points="11 5 6 9 2 9 2 15 6 15 11 19 11 5" />
+				<line x1="22" y1="9" x2="16" y2="15" />
+				<line x1="16" y1="9" x2="22" y2="15" />
+			</svg>
+			<!-- Playing: speaker with waves, lucide volume-2 geometry. -->
+			<svg
+				xmlns="http://www.w3.org/2000/svg"
+				viewBox="0 0 24 24"
+				fill="none"
+				stroke="currentColor"
+				stroke-width="2"
+				stroke-linecap="round"
+				stroke-linejoin="round"
+				class="glyph glyph-on absolute inset-0"
+				width={ICON_SIZE}
+				height={ICON_SIZE}
+			>
+				<polygon points="11 5 6 9 2 9 2 15 6 15 11 19 11 5" />
+				<path d="M15.54 8.46a5 5 0 0 1 0 7.07" />
+				<path d="M19.07 4.93a10 10 0 0 1 0 14.14" />
+			</svg>
+		</span>
+	</button>
+
+	<!-- Teaches the menu gestures to assistive tech (the gestures are not
+	     obvious from a button that both toggles and opens a menu). -->
+	<span id={hintId} class="sr-only">Press the down arrow, or press and hold or right-click, to choose a scape.</span>
+
+	{#if open}
+		<div
+			bind:this={panelRef}
+			id={menuId}
+			role="menu"
+			tabindex="-1"
+			aria-label="Ambience"
+			class="jatui-ambience-menu absolute z-50 w-72 max-w-[calc(100vw-1rem)] overflow-y-auto
+				rounded-box border border-base-300 bg-base-100 p-1.5 text-base-content shadow-xl
+				max-h-[min(24rem,calc(100vh-1rem))] menu-pop
+				{PLACEMENT_CLASS[effectivePlacement]}"
+			onkeydown={onMenuKeydown}
+		>
+			<!-- Volume: a real slider in the roving set; it owns its own arrows. -->
+			<div role="none" class="mb-1 border-b border-base-content/10 px-2 pb-2.5 pt-1.5">
+				<div class="mb-1.5 flex items-center justify-between">
+					<span class="text-jatui-label text-base-content/60">Volume</span>
+					<span class="text-2xs text-base-content/50 tabular-nums">{sliderValue}%</span>
+				</div>
+				<input
+					data-ambience-nav
+					tabindex="-1"
+					type="range"
+					class="range range-xs w-full"
+					min="0"
+					max="100"
+					step="1"
+					value={sliderValue}
+					aria-label="Ambience volume"
+					aria-valuetext="{sliderValue}%"
+					oninput={onVolumeInput}
+				/>
+			</div>
+
+			{#each groups as g (g.group)}
+				<div role="group" aria-label={g.label} class="py-1">
+					<div class="text-jatui-label text-base-content/45 px-2 py-1" aria-hidden="true">
+						{g.label}
+					</div>
+					{#each g.scapes as s (s.id)}
+						<button
+							type="button"
+							role="menuitemradio"
+							aria-checked={s.id === currentId}
+							tabindex="-1"
+							data-ambience-nav
+							class="flex w-full items-start gap-2 rounded px-2 py-1.5 text-left
+								transition-colors duration-[var(--motion-instant,80ms)]
+								hover:bg-base-content/10 focus-visible:bg-base-content/10
+								focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-primary
+								{s.id === currentId ? 'bg-base-content/5' : ''}"
+							onclick={() => selectScape(s)}
+						>
+							<span class="min-w-0 flex-1">
+								<span class="block truncate text-sm font-medium">{s.label}</span>
+								{#if s.description}
+									<!-- Secondary line: for playlist scapes this is the track attribution. -->
+									<span class="text-2xs text-base-content/55 block truncate">{s.description}</span>
+								{/if}
+							</span>
+							{#if s.id === currentId}
+								<svg
+									xmlns="http://www.w3.org/2000/svg"
+									viewBox="0 0 24 24"
+									fill="currentColor"
+									class="mt-1 size-3.5 shrink-0 text-primary"
+									aria-hidden="true"
+								>
+									<path d="M20.285 2l-11.285 11.567-5.286-5.011-3.714 3.716 9 8.728 15-15.285z"></path>
+								</svg>
+							{:else}
+								<span class="mt-1 size-3.5 shrink-0" aria-hidden="true"></span>
+							{/if}
+						</button>
+					{/each}
+				</div>
+			{/each}
+		</div>
+	{/if}
+
+	<!-- Live status: announces play/stop/switch without stealing focus. -->
+	<span role="status" aria-live="polite" class="sr-only">{liveLabel}</span>
+</div>
+
+<style>
+	/*
+	 * Off↔on morph: transform + opacity only (compositor-friendly), spring for
+	 * the small-element settle, glide for the fade — the ThemeToggle recipe.
+	 */
+	.glyph {
+		transition:
+			transform var(--motion-fast, 150ms) var(--motion-spring, cubic-bezier(0.34, 1.56, 0.64, 1)),
+			opacity var(--motion-fast, 150ms) var(--motion-glide, cubic-bezier(0.16, 1, 0.3, 1));
+	}
+
+	.glyph-off {
+		opacity: 1;
+		transform: rotate(0deg) scale(1);
+	}
+
+	.glyph-on {
+		opacity: 0;
+		transform: rotate(-90deg) scale(0.5);
+	}
+
+	.is-playing .glyph-off {
+		opacity: 0;
+		transform: rotate(90deg) scale(0.5);
+	}
+
+	.is-playing .glyph-on {
+		opacity: 1;
+		transform: rotate(0deg) scale(1);
+	}
+
+	/*
+	 * The breath: the engine's shared breath clock drives
+	 * --jatui-ambience-breath at its ~4 Hz tick; the transition interpolates
+	 * between the steps so the glyph visibly inhales and exhales.
+	 */
+	.glyphs {
+		transform: scale(var(--jatui-ambience-breath, 1));
+		transition: transform 420ms var(--motion-glide, cubic-bezier(0.16, 1, 0.3, 1));
+	}
+
+	/* Ambient decorative loop — static under reduced motion … */
+	@media (prefers-reduced-motion: reduce) {
+		.glyph {
+			transition: none;
+		}
+		.glyphs {
+			transform: none;
+			transition: none;
+		}
+		.menu-pop {
+			animation: none;
+		}
+	}
+
+	/* … and under data-motion="calm" (the house rule for ambient loops). */
+	:global([data-motion='calm']) .glyphs {
+		transform: none;
+	}
+
+	.menu-pop {
+		animation: jatui-menu-in var(--motion-enter, 200ms) var(--motion-glide, cubic-bezier(0.16, 1, 0.3, 1));
+	}
+
+	@keyframes jatui-menu-in {
+		from {
+			opacity: 0;
+		}
+	}
+</style>