@joewinke/jatui 0.54.1 → 0.56.0

package/dist/components/AmbienceToggle.svelte

@@ -6,16 +6,30 @@
 	 *
 	 * 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
+	 *     engine call, made synchronously inside the click handler. With no
+	 *     playable scape registered (links only) the click opens the menu.
+	 *   - The 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.
+	 *     the keyboard path always works). Top level: a volume slider wired to
+	 *     `engine.setVolume`, then one row per section — Radio / Focus /
+	 *     Noise / Meditation … in the host's order (`AmbienceOptions.groups`,
+	 *     jatui-mdq2p) — each opening a submenu of its items. Right / Enter /
+	 *     Space open a submenu and move focus into it; Left / Escape close it
+	 *     and return focus to its row (the ContextMenu submenu pattern); a
+	 *     mouse hover opens a row's submenu without moving focus.
+	 *   - Scapes are `menuitemradio` (current one checked; its section row
+	 *     carries a dot and the scape's name). Link items (radio stations) are
+	 *     real `<a target="_blank">` menu items with an external-link glyph:
+	 *     the station's own site or player opens in a new tab. Nothing is
+	 *     relayed — we never proxy a third-party stream.
+	 *   - A playing playlist shows its current track's attribution (title,
+	 *     composer, license) under the playlist item and its section row.
+	 *   - With a menu or submenu open, the mouse wheel over that surface
+	 *     adjusts volume (wheel up = louder, ~5% per notch; the list still
+	 *     scrolls while it has room) — the wheel escapes to the page the moment
+	 *     the pointer leaves the surface. Each surface (panel and any open
+	 *     submenu) carries its own non-passive listener; never window.
 	 *
 	 * A11y: the trigger is `aria-pressed` while playing and carries the full
 	 * menu-button wiring (`aria-expanded` / `aria-haspopup` / `aria-controls`).
@@ -28,58 +42,41 @@
 	 * 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[];
-	}
+	import type { AmbienceGroupDef, AmbienceItem, ScapeGroup } from '../ambience/types';
+	import {
+		AMBIENCE_DEFAULT_GROUP_LABELS,
+		AMBIENCE_DEFAULT_GROUP_ORDER,
+		groupAmbienceItems,
+		type AmbienceSection
+	} from '../ambience/groups';
+	import { trackAttribution, type PlaylistTrack } from '../ambience/scapes/playlist';
+
+	/** Default menu section order (when the host configures no `groups`). */
+	export const AMBIENCE_GROUP_ORDER: readonly ScapeGroup[] = AMBIENCE_DEFAULT_GROUP_ORDER;
+
+	/** Human labels for the library's own groups. */
+	export const GROUP_LABELS: Readonly<Record<string, string>> = AMBIENCE_DEFAULT_GROUP_LABELS;
+
+	/** One section of the menu: a top-level row and its submenu. */
+	export type AmbienceScapeGroup = AmbienceSection;
 
 	/**
-	 * 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.
+	 * Group items for the menu: the host's section order (or the default),
+	 * registration order within a section, empty sections omitted. A group
+	 * missing from the order still renders, after the ordered ones, in
+	 * first-seen order — a menu never silently drops a registered item.
 	 */
-	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;
+	export function groupScapes(
+		items: AmbienceItem[],
+		groups?: ReadonlyArray<ScapeGroup | AmbienceGroupDef>
+	): AmbienceScapeGroup[] {
+		return groupAmbienceItems(items, groups);
+	}
+
+	/** "Gymnopédie No. 1 — Erik Satie · Public domain": a playing track's line. */
+	export function nowPlayingLine(track: PlaylistTrack | null | undefined): string {
+		if (!track) return '';
+		return `${track.title} — ${trackAttribution(track)}`;
 	}
 
 	/**
@@ -106,17 +103,111 @@
 		const v = Math.min(1, Math.max(0, value));
 		return 1 + 0.06 * v;
 	}
+
+	/** Submenu width (px) — matches the `w-64` class on the submenu panel. */
+	export const SUBMENU_WIDTH = 256;
+
+	/**
+	 * Where a submenu goes, in viewport px. Beside the menu panel on the
+	 * preferred side (the side the menu already extends to), else the other
+	 * side, else — a phone, no room either side — overlapping the panel just
+	 * below its row, clamped inside the viewport.
+	 */
+	export function placeSubmenu(
+		row: { top: number; bottom: number },
+		panel: { left: number; right: number },
+		viewport: { width: number },
+		prefer: 'left' | 'right',
+		width = SUBMENU_WIDTH,
+		gap = 4,
+		margin = 8
+	): { x: number; y: number; side: 'left' | 'right' | 'over' } {
+		const right = panel.right + gap;
+		const left = panel.left - gap - width;
+		const fitsRight = right + width <= viewport.width - margin;
+		const fitsLeft = left >= margin;
+		const y = row.top - 6;
+		if (prefer === 'left' ? fitsLeft : fitsRight)
+			return { x: prefer === 'left' ? left : right, y, side: prefer };
+		if (prefer === 'left' ? fitsRight : fitsLeft)
+			return { x: prefer === 'left' ? right : left, y, side: prefer === 'left' ? 'right' : 'left' };
+		const x = Math.max(margin, Math.min(panel.left + 16, viewport.width - margin - width));
+		return { x, y: row.bottom + 2, side: 'over' };
+	}
+
+	// --- wheel volume over the open surfaces (jatui-xomny) -------------------
+
+	/** One mouse-wheel notch in pixel mode — Chrome/WebKit ship ±100 per notch. */
+	export const WHEEL_NOTCH_PX = 100;
+	/** One mouse-wheel notch in line mode — Firefox ships ±3 lines per notch. */
+	export const WHEEL_NOTCH_LINES = 3;
+	/** Volume change per wheel notch, on the 0-100 slider scale. */
+	export const WHEEL_STEP_PCT = 5;
+
+	/**
+	 * A wheel delta normalized into notch units (~1 = one physical notch):
+	 * pixel deltas divide by ~100 px, Firefox's line mode by 3 lines, and a
+	 * page-mode delta counts as one notch. Trackpads emit small pixel deltas
+	 * continuously — those are meant to accumulate (see wheelVolumeSteps),
+	 * not to step on every event.
+	 */
+	export function wheelNotches(deltaY: number, deltaMode: number): number {
+		if (deltaY === 0) return 0;
+		if (deltaMode === 1) return deltaY / WHEEL_NOTCH_LINES; // lines
+		if (deltaMode === 2) return deltaY; // one page ≈ one notch
+		return deltaY / WHEEL_NOTCH_PX; // pixels (deltaMode 0)
+	}
+
+	/**
+	 * Accumulate a wheel delta into `acc` and return the WHOLE volume steps it
+	 * adds up to, in volume terms — positive = louder (wheel up), negative =
+	 * quieter (wheel down) — 0 while a partial notch is still pending. The
+	 * remainder stays in `acc.value` across events, so trackpad pixel deltas
+	 * accumulate and one wheel notch lands as about one step.
+	 */
+	export function wheelVolumeSteps(
+		acc: { value: number },
+		deltaY: number,
+		deltaMode: number
+	): number {
+		acc.value += wheelNotches(deltaY, deltaMode);
+		// Wheel down (positive delta) quiets — flip the sign into volume steps.
+		// +0 normalizes Math.trunc's negative zero, which toBe/toEqual treat as
+		// a different value from 0.
+		const steps = Math.trunc(-acc.value) + 0;
+		if (steps !== 0) acc.value += steps; // consume the whole steps
+		return steps;
+	}
+
+	/**
+	 * The volume (0..1) after `steps` wheel steps: ±`stepPct` per step on the
+	 * 0-100 slider scale, clamped to 0-100. The math runs on the rounded
+	 * slider percent, so the result never carries float dust past what the
+	 * slider itself would produce for the same value.
+	 */
+	export function volumeAfterSteps(
+		volume: number,
+		steps: number,
+		stepPct = WHEEL_STEP_PCT
+	): number {
+		const next = Math.round(volume * 100) + steps * stepPct;
+		return Math.min(100, Math.max(0, next)) / 100;
+	}
 </script>
 
 <script lang="ts">
+	import { untrack } from 'svelte';
 	import { getMotionContext } from '../motion/level';
+	import { isAmbienceLink, safeAmbienceHref } from '../ambience/groups';
+	import { isPlaylistScape, type PlaylistState } from '../ambience/scapes/playlist';
+	import type { Ambience, AmbienceLink, Scape } from '../ambience/types';
 
 	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. */
+		/** The engine instance (from `createAmbience()`). The component never creates one, and never kills it — the host owns the engine's lifecycle. Section order/labels come from the engine's `groups` option. */
 		engine: Ambience;
 		/** Smaller app-shell footprint: 40px trigger with an 18px glyph (default 44px / 20px). Never below the 40px touch floor. */
 		compact?: boolean;
@@ -126,6 +217,7 @@
 
 	const menuId = $props.id();
 	const hintId = `${menuId}-hint`;
+	const subId = `${menuId}-sub`;
 
 	/** Long-press duration for the pointer path to the menu. */
 	const LONG_PRESS_MS = 450;
@@ -135,37 +227,64 @@
 	let playing = $state(false);
 	let currentId = $state<string | null>(null);
 	let volume = $state(0.6);
-	let scapes = $state<Scape[]>([]);
+	let items = $state<AmbienceItem[]>([]);
 	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
 	);
 
+	/** The section whose submenu is open (null = none), and where it sits
+	 *  relative to the wrapper (the submenu's offset parent). */
+	let subGroup = $state<string | null>(null);
+	let subPos = $state<{ left: number; top: number; side: 'left' | 'right' | 'over' }>({
+		left: 0,
+		top: 0,
+		side: 'right'
+	});
+
 	/** 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 wrapRef = $state<HTMLDivElement | null>(null);
 	let btnRef = $state<HTMLButtonElement | null>(null);
 	let panelRef = $state<HTMLDivElement | null>(null);
+	let subRef = $state<HTMLDivElement | null>(null);
 	let glyphRef = $state<HTMLSpanElement | null>(null);
+	/** The volume section (header + slider) at the top of the panel. */
+	let volumeRef = $state<HTMLDivElement | null>(null);
 
 	let playError = $state(false);
+	let track = $state<PlaylistState['track']>(null);
 
-	const currentScape = $derived(scapes.find((s) => s.id === currentId) ?? null);
-	const currentLabel = $derived(currentScape?.label ?? currentId);
-	const groups = $derived(groupScapes(scapes));
+	// Wheel-volume accumulator over the open surfaces (jatui-xomny): carries
+	// the pending partial notch between wheel events so trackpad pixel deltas
+	// accumulate into whole steps. Reset every time the menu opens; shared by
+	// the panel and its submenus for continuity.
+	const wheelAcc = { value: 0 };
+
+	const scapes = $derived(items.filter((i): i is Scape => !isAmbienceLink(i)));
+	const currentItem = $derived(items.find((s) => s.id === currentId) ?? null);
+	const currentLabel = $derived(currentItem?.label ?? currentId);
+	const groups = $derived(groupScapes(items, engine.groups?.()));
+	const openSection = $derived(groups.find((g) => g.group === subGroup) ?? null);
+	const trackLine = $derived(playing ? nowPlayingLine(track) : '');
 	const liveLabel = $derived(
 		playError ? PLAY_ERROR_LABEL : ambienceLiveLabel(currentLabel, playing)
 	);
-	const disabled = $derived(scapes.length === 0);
+	const disabled = $derived(items.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);
 
+	function snapshot(): AmbienceItem[] {
+		return engine.items?.() ?? engine.list();
+	}
+
 	// Engine state → component state. subscribe() fires once immediately, so
 	// this also fills the initial (persisted-preselect) state at mount.
 	$effect(() => {
@@ -173,12 +292,24 @@
 			playing = s.playing;
 			currentId = s.currentId;
 			volume = s.volume;
-			scapes = engine.list();
+			items = snapshot();
 			// A successful play (state flips to playing) clears the failure.
 			if (s.playing) playError = false;
 		});
 	});
 
+	// The current scape is a playlist → follow its track for the attribution line.
+	$effect(() => {
+		const item = currentItem;
+		if (!isPlaylistScape(item)) {
+			track = null;
+			return;
+		}
+		return item.subscribe((s) => {
+			track = s.status === 'playing' ? s.track : null;
+		});
+	});
+
 	// 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
@@ -201,8 +332,10 @@
 	});
 
 	// 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.
+	// begins outside never reaches the page first), the non-passive wheel
+	// listener on the PANEL element (never window — see onSurfaceWheel), and
+	// APG focus movement into the menu — focus the first nav item once the
+	// panel exists. A resize closes an open submenu (its position is stale).
 	$effect(() => {
 		if (!open) return;
 		const panel = panelRef;
@@ -210,17 +343,60 @@
 		navItems()[0]?.focus();
 		const onDocPointerDown = (e: PointerEvent) => {
 			const t = e.target as Node | null;
-			if (btnRef?.contains(t) || panelRef?.contains(t)) return;
+			if (btnRef?.contains(t) || panelRef?.contains(t) || subRef?.contains(t)) return;
 			closeMenu(false);
 		};
+		const onResize = () => closeSubmenu(false);
 		document.addEventListener('pointerdown', onDocPointerDown, true);
-		return () => document.removeEventListener('pointerdown', onDocPointerDown, true);
+		window.addEventListener('resize', onResize);
+		panel.addEventListener('wheel', onPanelWheel, { passive: false });
+		return () => {
+			document.removeEventListener('pointerdown', onDocPointerDown, true);
+			window.removeEventListener('resize', onResize);
+			panel.removeEventListener('wheel', onPanelWheel);
+		};
 	});
 
+	// Non-passive wheel on any open submenu too (jatui-xomny): over the
+	// submenu the wheel is volume with the same rule — a list that can still
+	// scroll keeps scrolling. The submenu is a SIBLING of the panel (never
+	// clipped by its scroll box), so it carries its own listener.
+	$effect(() => {
+		const sub = subRef;
+		if (!open || !sub || subGroup === null) return;
+		const onSubWheel = (e: WheelEvent) => onSurfaceWheel(e, sub, false);
+		sub.addEventListener('wheel', onSubWheel, { passive: false });
+		return () => sub.removeEventListener('wheel', onSubWheel);
+	});
+
+	// Keep an open submenu inside the viewport vertically once its real
+	// height is known.
+	$effect(() => {
+		const sub = subRef;
+		const wrap = wrapRef;
+		if (!sub || !wrap || !subGroup) return;
+		const r = sub.getBoundingClientRect();
+		const overflow = r.bottom - (window.innerHeight - 8);
+		if (overflow > 0) {
+			const wrapTop = wrap.getBoundingClientRect().top;
+			const pos = untrack(() => subPos);
+			subPos = { ...pos, top: Math.max(8 - wrapTop, pos.top - overflow) };
+		}
+	});
+
+	/** Top-level roving set: the volume slider and the section rows. */
 	function navItems(): HTMLElement[] {
 		return panelRef ? Array.from(panelRef.querySelectorAll<HTMLElement>('[data-ambience-nav]')) : [];
 	}
 
+	function subItems(): HTMLElement[] {
+		return subRef ? Array.from(subRef.querySelectorAll<HTMLElement>('[data-ambience-sub]')) : [];
+	}
+
+	function rowFor(group: string): HTMLElement | null {
+		return panelRef?.querySelector<HTMLElement>(`[data-ambience-group="${CSS.escape(group)}"]`) ?? null;
+	}
+
 	function resolvePlacement(): 'bottom-start' | 'bottom-end' | 'top-start' | 'top-end' {
 		const el = btnRef;
 		if (!el || typeof window === 'undefined') return placement;
@@ -236,17 +412,57 @@
 
 	function openMenu() {
 		if (disabled) return;
-		scapes = engine.list(); // freshest registry snapshot for the menu
+		items = snapshot(); // freshest registry snapshot for the menu
 		effectivePlacement = resolvePlacement();
+		subGroup = null;
+		wheelAcc.value = 0; // a fresh menu starts from no pending wheel delta
 		open = true;
 	}
 
 	function closeMenu(refocus = true) {
 		if (!open) return;
 		open = false;
+		subGroup = null;
 		if (refocus) btnRef?.focus();
 	}
 
+	function openSubmenu(group: string, focusFirst: boolean) {
+		const row = rowFor(group);
+		const wrap = wrapRef;
+		if (!row || !wrap || !panelRef) return;
+		const rr = row.getBoundingClientRect();
+		const pr = panelRef.getBoundingClientRect();
+		const wr = wrap.getBoundingClientRect();
+		const prefer = effectivePlacement.endsWith('end') ? 'left' : 'right';
+		const p = placeSubmenu(rr, pr, { width: window.innerWidth }, prefer);
+		subPos = { left: p.x - wr.left, top: p.y - wr.top, side: p.side };
+		subGroup = group;
+		if (focusFirst) queueMicrotask(() => subItems()[0]?.focus());
+	}
+
+	function closeSubmenu(refocusRow = true) {
+		const g = subGroup;
+		if (g === null) return;
+		subGroup = null;
+		if (refocusRow) rowFor(g)?.focus();
+	}
+
+	function onRowClick(e: MouseEvent, group: string) {
+		// Keyboard activation (Enter / Space → detail 0) always opens and enters;
+		// a mouse click on the open row's own submenu toggles it shut.
+		if (e.detail > 0 && subGroup === group) {
+			closeSubmenu(true);
+			return;
+		}
+		openSubmenu(group, true);
+	}
+
+	function onRowPointerEnter(e: PointerEvent, group: string) {
+		// Hover opens (mouse/pen only — a touch tap is a click). Focus stays put.
+		if (e.pointerType === 'touch' || subGroup === group) return;
+		openSubmenu(group, false);
+	}
+
 	function togglePlay(e: MouseEvent) {
 		// A long-press already opened the menu — don't also fire the toggle
 		// (keyboard activations, detail 0, are never suppressed).
@@ -255,13 +471,22 @@
 			return;
 		}
 		longPressed = false;
-		if (open) closeMenu(false);
+		if (open) {
+			closeMenu(false);
+			if (!engine.list().length) return;
+		}
 		if (playing) {
 			engine.stop();
 			return;
 		}
-		const id = engine.state.currentId ?? engine.list()[0]?.id;
-		if (!id) return;
+		const playable = engine.list();
+		const last = engine.state.currentId;
+		const id = last && playable.some((s) => s.id === last) ? last : playable[0]?.id;
+		if (!id) {
+			// Links only (e.g. a radio-only shell): the trigger opens the menu.
+			openMenu();
+			return;
+		}
 		attemptPlay(id);
 	}
 
@@ -286,11 +511,84 @@
 		attemptPlay(scape.id);
 	}
 
+	function onLinkClick() {
+		// The anchor's own default action opens the new tab; just get out of the way.
+		closeMenu(false);
+	}
+
 	function onVolumeInput(e: Event) {
 		const v = Number((e.currentTarget as HTMLInputElement).value);
 		engine.setVolume(v / 100);
 	}
 
+	// --- wheel volume over the open surfaces (jatui-xomny) -------------------
+	// While the menu (or one of its submenus) is open the wheel adjusts volume
+	// instead of scrolling the page — EXCEPT over a scrollable list that can
+	// still move in the wheel's direction, where the wheel stays a scroll. The
+	// listeners are non-passive on the surface elements (the panel and any
+	// open submenu — the submenu is a SIBLING of the panel, so it needs its
+	// own) and are only attached while open, so a wheel anywhere else scrolls
+	// the page exactly as before.
+
+	/**
+	 * The elements a native wheel scroll could move for a target inside
+	 * `surface`: every HTMLElement from the target up to and including the
+	 * surface itself (the panel and each submenu are their own
+	 * `overflow-y-auto` scroll containers).
+	 */
+	function scrollablesBetween(target: Node, surface: HTMLElement): HTMLElement[] {
+		const out: HTMLElement[] = [];
+		let el: Node | null = target;
+		while (el && el !== surface) {
+			if (el instanceof HTMLElement) out.push(el);
+			el = el.parentNode;
+		}
+		out.push(surface);
+		return out;
+	}
+
+	/** Can `el` still move in the wheel's direction? (1px epsilon: a list
+	 *  sitting at its edge with sub-pixel scrollTop is at the end.) */
+	function canScrollFurther(el: HTMLElement, down: boolean): boolean {
+		const style = getComputedStyle(el);
+		const scrolls =
+			(style.overflowY === 'auto' || style.overflowY === 'scroll') &&
+			el.scrollHeight > el.clientHeight;
+		if (!scrolls) return false;
+		return down ? el.scrollTop + el.clientHeight < el.scrollHeight - 1 : el.scrollTop > 1;
+	}
+
+	/**
+	 * The shared wheel handler for one open surface. `hasVolume` marks the
+	 * panel — the surface that owns the volume section, where the wheel is
+	 * ALWAYS volume (it is a control, not a list). Over the list rows the
+	 * wheel stays a scroll while some scrollable under the pointer can still
+	 * move that way; past the end (or when the list is shorter than the
+	 * surface) it steps the volume instead of letting the scroll escape to
+	 * the page.
+	 */
+	function onSurfaceWheel(e: WheelEvent, surface: HTMLElement, hasVolume: boolean) {
+		const target = e.target as Node | null;
+		if (!target || !surface.contains(target)) return;
+		// Vertical wheel only — shift+wheel is horizontal scrolling.
+		if (e.deltaY === 0) return;
+		const down = e.deltaY > 0;
+		const overVolume = hasVolume && (volumeRef?.contains(target) ?? false);
+		const hijack =
+			overVolume || !scrollablesBetween(target, surface).some((el) => canScrollFurther(el, down));
+		if (!hijack) return; // native scroll — never preventDefault, never step
+
+		e.preventDefault();
+		const steps = wheelVolumeSteps(wheelAcc, e.deltaY, e.deltaMode);
+		if (steps !== 0) engine.setVolume(volumeAfterSteps(volume, steps));
+	}
+
+	function onPanelWheel(e: WheelEvent) {
+		const panel = panelRef;
+		if (!panel) return;
+		onSurfaceWheel(e, panel, true);
+	}
+
 	// --- pointer path to the menu: press-and-hold ----------------------------
 	function onPointerDown(e: PointerEvent) {
 		longPressed = false;
@@ -331,11 +629,25 @@
 		}
 	}
 
-	// --- menu keyboard: APG roving among the nav items -----------------------
+	/** APG roving: next index for an arrow / Home / End key, wrapping. */
+	function rove(list: HTMLElement[], key: string): void {
+		if (!list.length) return;
+		const current = list.indexOf(document.activeElement as HTMLElement);
+		let next: number;
+		if (key === 'Home') next = 0;
+		else if (key === 'End') next = list.length - 1;
+		else if (current === -1) next = key === 'ArrowUp' ? list.length - 1 : 0;
+		else if (key === 'ArrowDown') next = (current + 1) % list.length;
+		else next = (current - 1 + list.length) % list.length;
+		list[next]?.focus();
+	}
+
+	// --- top-level menu keyboard ---------------------------------------------
 	function onMenuKeydown(e: KeyboardEvent) {
 		if (e.key === 'Escape') {
 			e.preventDefault();
-			closeMenu(true);
+			if (subGroup !== null) closeSubmenu(true);
+			else closeMenu(true);
 			return;
 		}
 		if (e.key === 'Tab') {
@@ -345,18 +657,56 @@
 		}
 		// The volume slider owns its own arrows/Home/End.
 		if (e.target instanceof HTMLInputElement) return;
+		const group = (e.target as HTMLElement | null)?.dataset?.ambienceGroup;
+		// Enter / Space reach onRowClick as a native click (detail 0).
+		if (group && e.key === 'ArrowRight') {
+			e.preventDefault();
+			openSubmenu(group, true);
+			return;
+		}
+		if (e.key === 'ArrowLeft' && subGroup !== null) {
+			e.preventDefault();
+			closeSubmenu(true);
+			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();
+		// Moving between rows closes a hover-opened submenu.
+		if (subGroup !== null) subGroup = null;
+		rove(navItems(), e.key);
+	}
+
+	// --- submenu keyboard -----------------------------------------------------
+	function onSubKeydown(e: KeyboardEvent) {
+		if (e.key === 'Escape' || e.key === 'ArrowLeft') {
+			e.preventDefault();
+			closeSubmenu(true);
+			return;
+		}
+		if (e.key === 'Tab') {
+			closeMenu(false);
+			return;
+		}
+		if (e.key === ' ' && e.target instanceof HTMLAnchorElement) {
+			// Links activate on Enter natively; Space is the menuitem convention.
+			e.preventDefault();
+			e.target.click();
+			return;
+		}
+		if (!['ArrowDown', 'ArrowUp', 'Home', 'End'].includes(e.key)) return;
+		e.preventDefault();
+		rove(subItems(), e.key);
+	}
+
+	/** The secondary line under a section row: what's current in it. */
+	function rowDetail(g: AmbienceScapeGroup): string {
+		if (!currentItem || currentItem.group !== g.group || isAmbienceLink(currentItem)) return '';
+		if (trackLine && isPlaylistScape(currentItem)) return `${currentItem.label} · ${trackLine}`;
+		return playing ? `${currentItem.label} · playing` : currentItem.label;
+	}
+
+	function linkHref(item: AmbienceLink): string | null {
+		return safeAmbienceHref(item.href);
 	}
 
 	const PLACEMENT_CLASS = {
@@ -365,9 +715,14 @@
 		'top-start': 'bottom-full left-0 mb-2',
 		'top-end': 'bottom-full right-0 mb-2'
 	} as const;
+
+	const ITEM_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`;
 </script>
 
-<div class="relative inline-flex shrink-0">
+<div bind:this={wrapRef} class="relative inline-flex shrink-0">
 	<button
 		bind:this={btnRef}
 		type="button"
@@ -455,9 +810,10 @@
 				max-h-[min(24rem,calc(100vh-1rem))] menu-pop
 				{PLACEMENT_CLASS[effectivePlacement]}"
 			onkeydown={onMenuKeydown}
+			onscroll={() => closeSubmenu(false)}
 		>
 			<!-- 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 role="none" bind:this={volumeRef} 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>
@@ -478,32 +834,124 @@
 			</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)}
+				{@const detail = rowDetail(g)}
+				{@const hasCurrent = !!currentItem && currentItem.group === g.group}
+				<button
+					type="button"
+					role="menuitem"
+					tabindex="-1"
+					data-ambience-nav
+					data-ambience-group={g.group}
+					aria-haspopup="menu"
+					aria-expanded={subGroup === g.group}
+					aria-controls={subGroup === g.group ? subId : undefined}
+					class="{ITEM_CLASS} items-center {subGroup === g.group ? 'bg-base-content/10' : ''}"
+					onclick={(e) => onRowClick(e, g.group)}
+					onpointerenter={(e) => onRowPointerEnter(e, g.group)}
+				>
+					<span class="min-w-0 flex-1">
+						<span class="block truncate text-sm font-medium">{g.label}</span>
+						{#if detail}
+							<span class="text-2xs text-base-content/55 block truncate">{detail}</span>
+						{/if}
+					</span>
+					{#if hasCurrent}
+						<!-- Current-scape marker: the section that holds it. -->
+						<span class="size-1.5 shrink-0 rounded-full bg-primary" aria-hidden="true"></span>
+						<span class="sr-only">(current)</span>
+					{/if}
+					<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="size-4 shrink-0 text-base-content/50 {subPos.side === 'left' && subGroup === g.group ? 'rotate-180' : ''}"
+						aria-hidden="true"
+					>
+						<path d="m9 18 6-6-6-6" />
+					</svg>
+				</button>
+			{/each}
+		</div>
+
+		{#if openSection}
+			<!-- Submenu: a sibling of the panel (never clipped by its scroll box),
+			     positioned against the wrapper. -->
+			<div
+				bind:this={subRef}
+				id={subId}
+				role="menu"
+				tabindex="-1"
+				aria-label={openSection.label}
+				data-side={subPos.side}
+				class="jatui-ambience-submenu absolute z-[51] w-64 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(22rem,calc(100vh-1rem))] menu-pop"
+				style="left: {subPos.left}px; top: {subPos.top}px"
+				onkeydown={onSubKeydown}
+			>
+				{#each openSection.scapes as s (s.id)}
+					{#if isAmbienceLink(s)}
+						{@const href = linkHref(s)}
+						<a
+							role="menuitem"
+							tabindex="-1"
+							data-ambience-sub
+							href={href ?? undefined}
+							target="_blank"
+							rel="noopener noreferrer"
+							aria-disabled={href ? undefined : 'true'}
+							class="{ITEM_CLASS} {href ? '' : 'pointer-events-none opacity-50'}"
+							onclick={onLinkClick}
+						>
+							<span class="min-w-0 flex-1">
+								<span class="block truncate text-sm font-medium">{s.label}</span>
+								{#if s.description}
+									<span class="text-2xs text-base-content/55 block truncate">{s.description}</span>
+								{/if}
+								<span class="sr-only">(opens in a new tab)</span>
+							</span>
+							<!-- External link, lucide external-link 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="mt-1 size-3.5 shrink-0 text-base-content/55"
+								aria-hidden="true"
+							>
+								<path d="M15 3h6v6" />
+								<path d="M10 14 21 3" />
+								<path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6" />
+							</svg>
+						</a>
+					{:else}
+						{@const isCurrent = s.id === currentId}
+						{@const line = isCurrent && trackLine && isPlaylistScape(s) ? trackLine : s.description}
 						<button
 							type="button"
 							role="menuitemradio"
-							aria-checked={s.id === currentId}
+							aria-checked={isCurrent}
 							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' : ''}"
+							data-ambience-sub
+							class="{ITEM_CLASS} {isCurrent ? '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 line}
+									<!-- Secondary line: a playing playlist's track attribution
+									     (title — composer · license), else the description. -->
+									<span class="text-2xs text-base-content/55 block truncate" title={line}>{line}</span>
 								{/if}
 							</span>
-							{#if s.id === currentId}
+							{#if isCurrent}
 								<svg
 									xmlns="http://www.w3.org/2000/svg"
 									viewBox="0 0 24 24"
@@ -517,10 +965,10 @@
 								<span class="mt-1 size-3.5 shrink-0" aria-hidden="true"></span>
 							{/if}
 						</button>
-					{/each}
-				</div>
-			{/each}
-		</div>
+					{/if}
+				{/each}
+			</div>
+		{/if}
 	{/if}
 
 	<!-- Live status: announces play/stop/switch without stealing focus. -->