@joewinke/jatui 0.54.1 → 0.56.0

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

@@ -5,16 +5,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`).
@@ -27,24 +41,24 @@
  * 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). */
+import type { AmbienceGroupDef, AmbienceItem, ScapeGroup } from '../ambience/types';
+import { type AmbienceSection } from '../ambience/groups';
+import { type PlaylistTrack } from '../ambience/scapes/playlist';
+/** Default menu section order (when the host configures no `groups`). */
 export declare const AMBIENCE_GROUP_ORDER: readonly ScapeGroup[];
-/** Human labels for the canonical groups. */
-export declare const GROUP_LABELS: Readonly<Record<ScapeGroup, string>>;
-/** One grouped section of the scape menu. */
-export interface AmbienceScapeGroup {
-    group: ScapeGroup;
-    label: string;
-    scapes: Scape[];
-}
+/** Human labels for the library's own groups. */
+export declare const GROUP_LABELS: Readonly<Record<string, string>>;
+/** 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 declare function groupScapes(scapes: Scape[]): AmbienceScapeGroup[];
+export declare function groupScapes(items: AmbienceItem[], groups?: ReadonlyArray<ScapeGroup | AmbienceGroupDef>): AmbienceScapeGroup[];
+/** "Gymnopédie No. 1 — Erik Satie · Public domain": a playing track's line. */
+export declare function nowPlayingLine(track: PlaylistTrack | null | undefined): string;
 /**
  * The live label — "Ambience: Hibiscus, playing" while sounding,
  * "Ambience: Hibiscus, stopped" once a scape has been selected but is not
@@ -61,8 +75,61 @@ export declare const PLAY_ERROR_LABEL = "Ambience: couldn't start \u2014 tap aga
  * and settles on the exhale — 6% total, clamped against out-of-range input.
  */
 export declare function breathScale(value: number): number;
+/** Submenu width (px) — matches the `w-64` class on the submenu panel. */
+export declare 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 declare function placeSubmenu(row: {
+    top: number;
+    bottom: number;
+}, panel: {
+    left: number;
+    right: number;
+}, viewport: {
+    width: number;
+}, prefer: 'left' | 'right', width?: number, gap?: number, margin?: number): {
+    x: number;
+    y: number;
+    side: 'left' | 'right' | 'over';
+};
+/** One mouse-wheel notch in pixel mode — Chrome/WebKit ship ±100 per notch. */
+export declare const WHEEL_NOTCH_PX = 100;
+/** One mouse-wheel notch in line mode — Firefox ships ±3 lines per notch. */
+export declare const WHEEL_NOTCH_LINES = 3;
+/** Volume change per wheel notch, on the 0-100 slider scale. */
+export declare 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 declare function wheelNotches(deltaY: number, deltaMode: number): number;
+/**
+ * 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 declare function wheelVolumeSteps(acc: {
+    value: number;
+}, deltaY: number, deltaMode: number): number;
+/**
+ * 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 declare function volumeAfterSteps(volume: number, steps: number, stepPct?: number): number;
+import type { Ambience } from '../ambience/types';
 type $$ComponentProps = {
-    /** 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;

package/dist/components/BottomSheet.svelte

@@ -30,6 +30,7 @@
 	import { scrollEdge as scrollEdgeAction } from '../actions/scrollEdge';
 	import { onMount, untrack } from 'svelte';
 	import type { ShortcutRegistry } from '../utils/keyboardShortcutRegistry';
+	import { focusDialogTarget, type InitialFocus } from '../utils/dialogFocus';
 	import type { Snippet } from 'svelte';
 	import { fly, fade } from 'svelte/transition';
 	import { cubicOut } from 'svelte/easing';
@@ -52,6 +53,7 @@
 		shortcutRegistry,
 		shortcutContext = 'bottom-sheet',
 		scrollEdge = true,
+		initialFocus = 'first-input',
 		children
 	}: {
 		open?: boolean;
@@ -75,9 +77,27 @@
 		shortcutContext?: string;
 		/** Soft progressive-blur fade at the top of the content once it scrolls (`use:scrollEdge`). Ignored with `fullHeight` (the slot owns scrolling). Default true. */
 		scrollEdge?: boolean;
+		/**
+		 * What to focus when the sheet opens. Default `'first-input'`:
+		 * [data-autofocus]/[autofocus] inside the panel, else the first enabled
+		 * text-entry control, else the panel itself. `'dialog'` focuses the
+		 * panel without searching; an HTMLElement or CSS selector targets
+		 * exactly that; `null` disables auto-focus entirely.
+		 */
+		initialFocus?: InitialFocus | null;
 		children?: Snippet;
 	} = $props();
 
+	// On open, focus the first fillable field — WAI-ARIA APG dialog pattern:
+	// focus the first field the user is expected to fill. See
+	// utils/dialogFocus.ts for the resolution order. `initialFocus = null`
+	// opts out entirely.
+	let panelElement: HTMLElement | undefined = $state();
+	$effect(() => {
+		if (!open || initialFocus === null) return;
+		focusDialogTarget(panelElement ?? null, { initialFocus, fallback: panelElement ?? null });
+	});
+
 	// While open, a modal shortcut context keeps the host page's registry
 	// shortcuts from firing behind it.
 	$effect(() => {
@@ -234,6 +254,7 @@
 		class="fixed bottom-0 inset-x-0 flex flex-col bg-base-100 rounded-t-2xl border-t border-base-300 shadow-2xl"
 		style="z-index: {zIndex + 1}; {panelHeightStyle} transform: translateY({dragCurrentY}px); opacity: {dragOpacity}; transition: {isDragging ? 'none' : 'transform 0.15s ease, opacity 0.15s ease, height 0.2s ease'};"
 		role="dialog"
+		bind:this={panelElement}
 		tabindex="-1"
 		aria-modal="true"
 		aria-label={title || 'Bottom sheet'}

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

@@ -1,4 +1,5 @@
 import type { ShortcutRegistry } from '../utils/keyboardShortcutRegistry';
+import { type InitialFocus } from '../utils/dialogFocus';
 import type { Snippet } from 'svelte';
 type $$ComponentProps = {
     open?: boolean;
@@ -22,6 +23,14 @@ type $$ComponentProps = {
     shortcutContext?: string;
     /** Soft progressive-blur fade at the top of the content once it scrolls (`use:scrollEdge`). Ignored with `fullHeight` (the slot owns scrolling). Default true. */
     scrollEdge?: boolean;
+    /**
+     * What to focus when the sheet opens. Default `'first-input'`:
+     * [data-autofocus]/[autofocus] inside the panel, else the first enabled
+     * text-entry control, else the panel itself. `'dialog'` focuses the
+     * panel without searching; an HTMLElement or CSS selector targets
+     * exactly that; `null` disables auto-focus entirely.
+     */
+    initialFocus?: InitialFocus | null;
     children?: Snippet;
 };
 declare const BottomSheet: import("svelte").Component<$$ComponentProps, {}, "open">;

package/dist/components/ConfirmModal.svelte

@@ -3,6 +3,7 @@
   import { cubicOut } from 'svelte/easing';
   import { untrack } from 'svelte';
   import type { ShortcutRegistry } from '../utils/keyboardShortcutRegistry';
+  import { focusDialogTarget, type InitialFocus } from '../utils/dialogFocus';
 
   let {
     open = $bindable(true),
@@ -17,6 +18,7 @@
     oncancel,
     shortcutRegistry,
     shortcutContext = 'confirm-modal',
+    initialFocus = 'first-input',
   } = $props<{
     open?: boolean
     title?: string
@@ -32,6 +34,14 @@
     shortcutRegistry?: ShortcutRegistry
     /** Context name pushed while open. Default `'confirm-modal'`. */
     shortcutContext?: string
+    /**
+     * What to focus when the modal opens (see utils/dialogFocus.ts).
+     * Default `'first-input'` resolves [data-autofocus]/[autofocus], then a
+     * text-entry control, then falls back to the dialog box itself — a
+     * confirm dialog has no text field, so it lands on the safe dialog
+     * element, never the destructive button.
+     */
+    initialFocus?: InitialFocus
   }>()
 
   // While open, a modal shortcut context keeps the host page's registry
@@ -59,11 +69,7 @@
     if (typeof document === 'undefined') return
     if (open) {
       previousFocus = document.activeElement as HTMLElement
-      requestAnimationFrame(() => {
-        if (modalBox?.contains(document.activeElement)) return
-        const first = modalBox?.querySelector<HTMLElement>(FOCUSABLE)
-        ;(first ?? modalBox)?.focus()
-      })
+      focusDialogTarget(modalBox, { initialFocus, fallback: modalBox })
     } else if (previousFocus) {
       previousFocus.focus?.()
       previousFocus = null

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

@@ -1,4 +1,5 @@
 import type { ShortcutRegistry } from '../utils/keyboardShortcutRegistry';
+import { type InitialFocus } from '../utils/dialogFocus';
 type $$ComponentProps = {
     open?: boolean;
     title?: string;
@@ -14,6 +15,14 @@ type $$ComponentProps = {
     shortcutRegistry?: ShortcutRegistry;
     /** Context name pushed while open. Default `'confirm-modal'`. */
     shortcutContext?: string;
+    /**
+     * What to focus when the modal opens (see utils/dialogFocus.ts).
+     * Default `'first-input'` resolves [data-autofocus]/[autofocus], then a
+     * text-entry control, then falls back to the dialog box itself — a
+     * confirm dialog has no text field, so it lands on the safe dialog
+     * element, never the destructive button.
+     */
+    initialFocus?: InitialFocus;
 };
 declare const ConfirmModal: import("svelte").Component<$$ComponentProps, {}, "open">;
 type ConfirmModal = ReturnType<typeof ConfirmModal>;

package/dist/components/Drawer.svelte

@@ -12,6 +12,7 @@
 	import { scrollEdge as scrollEdgeAction } from '../actions/scrollEdge';
 	import { untrack, type Snippet } from 'svelte';
 	import type { ShortcutRegistry } from '../utils/keyboardShortcutRegistry';
+	import { focusDialogTarget, type InitialFocus } from '../utils/dialogFocus';
 
 	interface Props {
 		open?: boolean;
@@ -45,6 +46,15 @@
 		shortcutRegistry?: ShortcutRegistry;
 		/** Context name pushed while open. Default `'drawer'`. */
 		shortcutContext?: string;
+		/**
+		 * What to focus when the drawer opens. Default `'first-input'`:
+		 * [data-autofocus]/[autofocus] inside the panel, else the first enabled
+		 * text-entry control (text-like input, textarea, contenteditable —
+		 * never the header close button), else the panel itself. `'dialog'`
+		 * focuses the panel without searching for a field. An HTMLElement or
+		 * CSS selector targets exactly that; `null` disables auto-focus entirely.
+		 */
+		initialFocus?: InitialFocus | null;
 		onclose?: () => void;
 		class?: string;
 		headerActions?: Snippet;
@@ -67,6 +77,7 @@
 		trapKeys = true,
 		shortcutRegistry,
 		shortcutContext = 'drawer',
+		initialFocus = 'first-input',
 		onclose,
 		class: className = '',
 		headerActions,
@@ -96,6 +107,17 @@
 		onclose?.();
 	}
 
+	let panelElement: HTMLElement | undefined = $state();
+
+	// On open, focus the first fillable field — WAI-ARIA APG dialog pattern:
+	// focus the first field the user is expected to fill. See
+	// utils/dialogFocus.ts for the resolution order. `initialFocus = null`
+	// opts out entirely.
+	$effect(() => {
+		if (!open || initialFocus === null) return;
+		focusDialogTarget(panelElement ?? null, { initialFocus, fallback: panelElement ?? null });
+	});
+
 	function handleKeydown(e: KeyboardEvent) {
 		if (e.key === 'Escape' && open) {
 			e.stopImmediatePropagation();
@@ -140,6 +162,7 @@
 		? 'z-[101] translate-x-0'
 		: '-z-10 ' + (position === 'right' ? 'translate-x-full' : '-translate-x-full')} {className}"
 	role="dialog"
+	bind:this={panelElement}
 	aria-modal={open}
 	aria-label={title}
 	aria-hidden={!open}

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

@@ -1,5 +1,6 @@
 import { type Snippet } from 'svelte';
 import type { ShortcutRegistry } from '../utils/keyboardShortcutRegistry';
+import { type InitialFocus } from '../utils/dialogFocus';
 interface Props {
     open?: boolean;
     title?: string;
@@ -32,6 +33,15 @@ interface Props {
     shortcutRegistry?: ShortcutRegistry;
     /** Context name pushed while open. Default `'drawer'`. */
     shortcutContext?: string;
+    /**
+     * What to focus when the drawer opens. Default `'first-input'`:
+     * [data-autofocus]/[autofocus] inside the panel, else the first enabled
+     * text-entry control (text-like input, textarea, contenteditable —
+     * never the header close button), else the panel itself. `'dialog'`
+     * focuses the panel without searching for a field. An HTMLElement or
+     * CSS selector targets exactly that; `null` disables auto-focus entirely.
+     */
+    initialFocus?: InitialFocus | null;
     onclose?: () => void;
     class?: string;
     headerActions?: Snippet;

package/dist/components/InputDialog.svelte

@@ -30,7 +30,12 @@
 		if (visible && opts) {
 			value = '';
 			error = null;
-			tick().then(() => inputRef?.focus());
+			// Focus AND select the input (jatui-fo6o8) so a replacement value
+			// can be typed over immediately without a select-all gesture.
+			tick().then(() => {
+				inputRef?.focus();
+				inputRef?.select();
+			});
 		}
 	});
 

package/dist/components/Modal.svelte

@@ -9,6 +9,7 @@
 	import CloseButton from './CloseButton.svelte';
 	import { onMount, untrack } from 'svelte';
 	import type { ShortcutRegistry } from '../utils/keyboardShortcutRegistry';
+	import { focusDialogTarget, type InitialFocus } from '../utils/dialogFocus';
 	import { fly, fade } from 'svelte/transition';
 	import { cubicOut } from 'svelte/easing';
 
@@ -51,6 +52,15 @@
 		shortcutRegistry?: ShortcutRegistry;
 		/** Context name pushed while open. Default `'modal'`. */
 		shortcutContext?: string;
+		/**
+		 * What to focus when the modal opens. Default `'first-input'`:
+		 * [data-autofocus]/[autofocus] inside the dialog, else the first enabled
+		 * text-entry control (text-like input, textarea, contenteditable —
+		 * never the header close button), else the dialog itself. `'dialog'`
+		 * restores the old container-focus behaviour for read-only/confirm
+		 * dialogs. An HTMLElement or CSS selector targets exactly that.
+		 */
+		initialFocus?: InitialFocus;
 		onclose?: () => void;
 		onopen?: () => void;
 		header?: import('svelte').Snippet;
@@ -75,6 +85,7 @@
 		trapKeys = true,
 		shortcutRegistry,
 		shortcutContext = 'modal',
+		initialFocus = 'first-input',
 		onclose,
 		onopen,
 		header,
@@ -112,7 +123,11 @@
 		if (open) {
 			previousFocus = document.activeElement as HTMLElement;
 			document.body.style.overflow = 'hidden';
-			requestAnimationFrame(() => modalElement?.focus());
+			// Focus the first fillable field, not the dialog box — see
+			// utils/dialogFocus.ts for the resolution order. Falls back to the
+			// dialog itself when there is no text field, so Escape handling
+			// (owned on the dialog element) keeps working as before.
+			focusDialogTarget(modalElement, { initialFocus, fallback: modalElement });
 			onopen?.();
 		} else {
 			document.body.style.overflow = '';
@@ -143,13 +158,13 @@
 
 	function handleKeyDown(event: KeyboardEvent) {
 		// Escape is owned HERE on the dialog element, not by <svelte:window>.
-		// Modal focuses the dialog (tabindex=-1) on open, so in the default state
-		// keydown dispatches from the dialog itself — and the trapKeys
-		// stopPropagation below (which under Svelte 5 delegated events also
-		// blocks every window listener) would swallow Escape before the window
-		// handler could act: Esc did nothing unless focus was in a text field.
-		// Handling it at element level also guarantees a Modal opened inside a
-		// host Drawer closes before the drawer does.
+		// When no text field matched, Modal focuses the dialog (tabindex=-1) on
+		// open, so in that state keydown dispatches from the dialog itself — and
+		// the trapKeys stopPropagation below (which under Svelte 5 delegated
+		// events also blocks every window listener) would swallow Escape before
+		// the window handler could act. Handling it at element level also
+		// guarantees a Modal opened inside a host Drawer closes before the
+		// drawer does.
 		if (open && event.key === 'Escape' && closeOnEscape) {
 			event.preventDefault();
 			event.stopPropagation();

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

@@ -1,4 +1,5 @@
 import type { ShortcutRegistry } from '../utils/keyboardShortcutRegistry';
+import { type InitialFocus } from '../utils/dialogFocus';
 interface Props {
     open?: boolean;
     title?: string;
@@ -38,6 +39,15 @@ interface Props {
     shortcutRegistry?: ShortcutRegistry;
     /** Context name pushed while open. Default `'modal'`. */
     shortcutContext?: string;
+    /**
+     * What to focus when the modal opens. Default `'first-input'`:
+     * [data-autofocus]/[autofocus] inside the dialog, else the first enabled
+     * text-entry control (text-like input, textarea, contenteditable —
+     * never the header close button), else the dialog itself. `'dialog'`
+     * restores the old container-focus behaviour for read-only/confirm
+     * dialogs. An HTMLElement or CSS selector targets exactly that.
+     */
+    initialFocus?: InitialFocus;
     onclose?: () => void;
     onopen?: () => void;
     header?: import('svelte').Snippet;

package/dist/index.d.ts

@@ -408,8 +408,9 @@ export { default as ImageReveal } from './components/ImageReveal.svelte';
 export { imageRevealPhase, imageRevealBusy, imageRevealInitials, imageRevealSize, imageRevealTone, IMAGE_REVEAL_SIZES, IMAGE_REVEAL_RADIUS } from './components/imageReveal';
 export type { ImageRevealPhase, ImageRevealShape, ImageRevealSizeName, ImageRevealToneName, ImageRevealState } from './components/imageReveal';
 export { default as AmbienceToggle, AMBIENCE_GROUP_ORDER } from './components/AmbienceToggle.svelte';
-export { createAmbience, createDefaultAmbience, DEFAULT_SCAPES, BreathClock, BREATHS_PER_MINUTE, MASTER, ScapeRegistry, hibiscusScape, focusScape, noiseScapes, brownNoiseScape, pinkNoiseScape, whiteNoiseScape, rain, waves } from './ambience';
-export type { DefaultAmbienceOptions } from './ambience';
-export type { Ambience, AmbienceOptions, AmbienceState, BreathState, Scape, ScapeContext, ScapeGroup, ScapeInstance } from './ambience';
+export { createAmbience, createDefaultAmbience, DEFAULT_SCAPES, BreathClock, BREATHS_PER_MINUTE, MASTER, ScapeRegistry, hibiscusScape, focusScape, noiseScapes, brownNoiseScape, pinkNoiseScape, whiteNoiseScape, rain, waves, AMBIENCE_DEFAULT_GROUP_ORDER, AMBIENCE_DEFAULT_GROUP_LABELS, groupAmbienceItems, ambienceGroupLabel, isAmbienceLink, normalizeAmbienceGroups, radioStation, safeAmbienceHref } from './ambience';
+export type { DefaultAmbienceOptions, AmbienceSection } from './ambience';
+export type { Ambience, AmbienceGroupDef, AmbienceItem, AmbienceLink, AmbienceOptions, AmbienceState, BreathState, Scape, ScapeContext, ScapeGroup, ScapeInstance } from './ambience';
 export { createPlaylistScape } from './ambience';
+export { isPlaylistScape, trackAttribution } from './ambience';
 export type { PlaylistScape, PlaylistScapeOptions, PlaylistManifest, PlaylistState, PlaylistStatus, PlaylistTrack } from './ambience';

package/dist/index.js

@@ -457,7 +457,8 @@ export { imageRevealPhase, imageRevealBusy, imageRevealInitials, imageRevealSize
 // navigation; createDefaultAmbience() pre-registers every shipped scape
 // (hibiscus, focus, brown/pink/white noise, rain, waves).
 export { default as AmbienceToggle, AMBIENCE_GROUP_ORDER } from './components/AmbienceToggle.svelte';
-export { createAmbience, createDefaultAmbience, DEFAULT_SCAPES, BreathClock, BREATHS_PER_MINUTE, MASTER, ScapeRegistry, hibiscusScape, focusScape, noiseScapes, brownNoiseScape, pinkNoiseScape, whiteNoiseScape, rain, waves } from './ambience';
+export { createAmbience, createDefaultAmbience, DEFAULT_SCAPES, BreathClock, BREATHS_PER_MINUTE, MASTER, ScapeRegistry, hibiscusScape, focusScape, noiseScapes, brownNoiseScape, pinkNoiseScape, whiteNoiseScape, rain, waves, AMBIENCE_DEFAULT_GROUP_ORDER, AMBIENCE_DEFAULT_GROUP_LABELS, groupAmbienceItems, ambienceGroupLabel, isAmbienceLink, normalizeAmbienceGroups, radioStation, safeAmbienceHref } from './ambience';
 // Playlist scape (phase 2) — per-host, never in DEFAULT_SCAPES: build with
 // createPlaylistScape() and register on the engine yourself.
 export { createPlaylistScape } from './ambience';
+export { isPlaylistScape, trackAttribution } from './ambience';

package/dist/utils/dialogFocus.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Dialog focus resolution (jatui-fo6o8)
+ *
+ * Shared rule for every surface that opens an overlay dialog/panel
+ * (Modal, Drawer, BottomSheet, Confirm*, InputDialog): on open, focus in
+ * this order —
+ *
+ *   1. an element with [data-autofocus] or the `autofocus` attribute inside
+ *      the container (a consumer's explicit opt-in);
+ *   2. else the first ENABLED, RENDERED text-entry control in the body
+ *      (not the header close button — buttons never qualify anyway): a
+ *      text-like <input>, an enabled <textarea>, or a contenteditable
+ *      element;
+ *   3. else the container element itself (today's behaviour — keeps Escape
+ *      working for read-only / confirm dialogs, see Modal's Escape note).
+ *
+ * "Rendered" matters: a focus() on an element that is not actually visible
+ * (display:none, inside a collapsed <details>, a [hidden]/[inert] ancestor,
+ * or visibility:hidden) is a silent no-op that leaves focus on <body>, which
+ * breaks the dialog's own Escape handling (Modal owns Escape on the dialog
+ * element). Unrendered candidates are skipped, and after focusing the target
+ * is verified to actually hold focus — else the fallback/container is
+ * focused instead.
+ *
+ * WAI-ARIA APG dialog pattern: focus the first field the user is expected
+ * to fill. `initialFocus` overrides the whole order —
+ *
+ *   - `HTMLElement` / `string` (a CSS selector, resolved inside the
+ *     container): focus exactly that; falls through to the default order
+ *     when the selector matches nothing.
+ *   - `'dialog'`: always focus the container (old behaviour — right for
+ *     read-only / confirm dialogs).
+ *   - `'first-input'` (default): the 1→2→3 order above.
+ */
+export type InitialFocus = HTMLElement | string | 'dialog' | 'first-input';
+export interface FocusOptions {
+    /** Explicit target. Default `'first-input'`. */
+    initialFocus?: InitialFocus | null;
+    /** Element to focus when nothing matches. Default the container itself. */
+    fallback?: HTMLElement | null;
+}
+/** True for an element a user can type into: text-like input, enabled textarea, contenteditable. */
+export declare function isTextEntryControl(el: Element): boolean;
+/**
+ * Resolve the element a dialog should focus when it opens, per the order
+ * above. Returns null when nothing matches and there is no fallback.
+ */
+export declare function resolveDialogFocusTarget(container: HTMLElement | null, opts?: FocusOptions): HTMLElement | null;
+/**
+ * Focus a resolved target on the next frame (after the open transition has
+ * mounted the content). Mirrors the previous `requestAnimationFrame` timing
+ * so focus lands on real DOM, not a mounting tree.
+ */
+export declare function focusDialogTarget(container: HTMLElement | null, opts?: FocusOptions, rq?: typeof requestAnimationFrame): void;