@joewinke/jatui 0.55.0 → 0.57.0

package/CLAUDE.md

@@ -86,9 +86,9 @@ Then import:
 | `ActivityHeatmap` | GitHub-style activity-per-day calendar (calls/day, tasks closed/day): 7 weekday rows × week columns, default range = last 12 months, `weekStart`, 4-step `color-mix` ramp from one theme `tone` (no hex), one floating tooltip, legend + summary ("1,204 calls in the last year"). `role="grid"` with ONE tab stop: arrows move by day (↑↓) / week (←→), PgUp/PgDn 4 weeks, Home/End row ends, mod+Home/End range ends, Enter/Space select. Pure layout helpers exported (`buildHeatmap`, `moveHeatFocus`). | `data` (`{date, count}[]` or `getDate`/`getCount`), `start?`/`end?`, `weekStart?`, `unit?` ('call' or ['call','calls']), `formatLabel?`, `tone?`, `levels?`, `levelOf?`, `compact?`, `showLegend?`/`showWeekdays?`/`showMonths?`, `summary?`, `selected` (bindable), `onSelectDay?(date, count)`, `locale?` |
 | `StatusBadge` | Status indicator with dot | `status: StatusValue`, `label` |
 | `Card` | Content card container | `title`, `children` (snippet) |
-| `Modal` | Dialog overlay. `zIndex` accepts `number` OR any CSS `z-index` string, including `"var(--z-lightbox)"`. **Escape is owned by the dialog element itself** (not the window handler) — Modal focuses the dialog on open, so `trapKeys`' stopPropagation would otherwise swallow Esc before the window listener sees it; a Modal opened inside a host Drawer closes before the drawer. The component ships its own open-state `.modal-box` opacity rule, so it renders under DaisyUI 5 with no host global override. | `open` (bindable), `title`, `children` (snippet), `zIndex?: string \| number`, `trapKeys?`, `closeOnEscape?` |
+| `Modal` | Dialog overlay. `zIndex` accepts `number` OR any CSS `z-index` string, including `"var(--z-lightbox)"`. **On open, focus goes to the first fillable field** (WAI-ARIA APG): a `[data-autofocus]`/`autofocus` element, else the first enabled **rendered** text-entry control (readOnly/disabled textareas excluded, unrendered candidates skipped), else the dialog itself — `initialFocus` overrides the order (`'dialog'` restores the old container focus); the focus landing is verified, else the container is focused. When the dialog is the fallback focus, **Escape is owned by the dialog element itself** (not the window handler), so `trapKeys`' stopPropagation can't swallow Esc; a Modal opened inside a host Drawer closes before the drawer. The component ships its own open-state `.modal-box` opacity rule, so it renders under DaisyUI 5 with no host global override. | `open` (bindable), `title`, `children` (snippet), `zIndex?: string \| number`, `trapKeys?`, `closeOnEscape?`, `initialFocus?` |
 | `ConfirmModal` | Yes/no confirmation dialog | `open` (bindable), `title`, `message`, `onConfirm`, `onCancel` |
-| `Drawer` | Slide-out side panel. Header ✕ is a `CloseButton`; the body carries `use:scrollEdge` (opt out with `scrollEdge={false}`). | `open` (bindable), `side`, `scrollEdge?`, `children` (snippet) |
+| `Drawer` | Slide-out side panel. Header ✕ is a `CloseButton`; the body carries `use:scrollEdge` (opt out with `scrollEdge={false}`). On open it focuses the first fillable field ([data-autofocus]/autofocus, else first enabled **rendered** text-entry control, else the panel) — `initialFocus` (`null` opts out). | `open` (bindable), `side`, `initialFocus?`, `scrollEdge?`, `children` (snippet) |
 | `LoadingSpinner` | Spinner animation | `size`, `color` |
 | `Sparkline` | Inline mini chart | `data: number[]`, `width`, `height`, `color` |
 | `LazyImage` | Image with lazy loading + placeholder | `src`, `alt`, `placeholder` |
@@ -106,11 +106,11 @@ Then import:
 | `BatchJobTable` | Generic queue runner (harvested from vid-gen's BatchGenerator) — `<BatchJobTable generics T>` over bindable `JobRow<T>[]`; host supplies async `run(data, {signal, attempt, reportProgress})`. Concurrency cap, optional per-run `processLimit` (quota budget), rolling-average ETA, per-row status badge / progress / elapsed / retry / skip / cancel / reorder — each cell a snippet override (`statusCell`, `progressCell`, `elapsedCell`, `actionsCell`), host data columns via `headers` + `cells`, extra toolbar content via `toolbar`. Uses `showToast` / `showConfirm` (mount `ToastHost` + `ConfirmDialog`). Exposes `start()`/`pause()`/`cancel()`/`retryFailed()`/`clearFinished()`. Pure scheduling helpers exported too (`nextJobsToStart`, `moveJob`, `summarizeJobs`, `toJobRows`). | `jobs` (bindable), `run`, `concurrencyLimit?` (3), `processLimit?`, `autoStart?`, `notify?`, `confirmDestructive?`, `onJobDone?`, `onJobFailed?`, `onBatchDone?` |
 | `QuotaMeter` | "312 / 500 credits · resets in 4h 10m" bar — warning tint at `warnAt`, error at 100%. Presentational; the host owns the ledger. | `used`, `limit`, `resetsAt?`, `label?`, `unit?`, `warnAt?` (0.8), `size?` |
 | `VariantMatrixPicker` | Category/option chip grid for building a combinatorial variant matrix (harvested from vid-gen's FrameVariantGenerator, presets stripped — caller-supplied `categories`). Each category tab shows a live selection count and an additive/multiplicative badge: multiplicative selections cartesian-multiply the total, additive ones stack flat onto every combination. Live combination count in the footer; algebra exported separately as pure functions (`generateCombinations`, `countCombinations`, `variantCategoryMode`, `findVariantOption`, `generateVariantFilename`). | `categories: VariantCategory[]`, `selected` (bindable `VariantSelection`), `forceMode?`, `showCount?` (true), `countLabel?`, `onChange?`, `class?` |
-| `BottomSheet` | Mobile bottom sheet (upstreamed from the JAT IDE — jatui-rl7w6.2): drag handle with pointer capture, backdrop close, optional header. `snap='dual'` enables the inspector pattern — peek → expanded snap heights with flick-momentum release (fast flick ≥ 0.5 px/ms wins over position; flick down from peek dismisses) and `visualViewport` keyboard avoidance so content clears the soft keyboard. | `open` (bindable), `title?`, `zIndex?` (70), `fullHeight?`, `snap?` ('single'\|'dual'), `peekFraction?` (0.4), `expandedFraction?` (0.9), `onclose?`, `children` (snippet) |
+| `BottomSheet` | Mobile bottom sheet (upstreamed from the JAT IDE — jatui-rl7w6.2): drag handle with pointer capture, backdrop close, optional header. `snap='dual'` enables the inspector pattern — peek → expanded snap heights with flick-momentum release (fast flick ≥ 0.5 px/ms wins over position; flick down from peek dismisses) and `visualViewport` keyboard avoidance so content clears the soft keyboard. | `open` (bindable), `title?`, `zIndex?` (70), `fullHeight?`, `snap?` ('single'\|'dual'), `peekFraction?` (0.4), `expandedFraction?` (0.9), `onclose?`, `initialFocus?` ('first-input': [data-autofocus]/autofocus, else first enabled **rendered** text-entry control, else the panel; `null` opts out), `children` (snippet) |
 
 ### Agent surfaces (BoardUI wave 2)
 
-"Agent is working" UI. Free BoardUI items (agent-thinking, agent-log, composer-loader, notification-center) were ported under MIT — see `THIRD_PARTY_NOTICES.md`; AgentTaskList, Questionnaire and ContextMeter are clean-room. Demos: `/components/agent-thinking`, `agent-log`, `agent-task-list`, `questionnaire`, `context-meter`, `notification-center`, `composer-glow`, `streamed-text`.
+"Agent is working" UI. Free BoardUI items (agent-thinking, agent-log, composer-loader, notification-center) were ported under MIT — see `THIRD_PARTY_NOTICES.md`; AgentTaskList, Questionnaire and ContextMeter are clean-room. Demos: `/components/agent-thinking`, `agent-log`, `agent-task-list`, `questionnaire`, `context-meter`, `notification-center`, `composer-glow`, `streamed-text`, `chat-transcript`.
 
 | Component | Purpose | Key Props |
 |-----------|---------|-----------|
@@ -124,6 +124,7 @@ Then import:
 | `NotificationCenter` | Inbox panel: title + "N unread" + "Mark all read"; a tab list with count chips (default All / Mentions / System by `category`; `bind:tab` or uncontrolled `defaultTab`; arrows / Home / End switch tabs). Items are newest first under Today / Yesterday / This week / Earlier headers (`groupNotificationsByDate`, `now` injectable). Roving focus via `createListNav`, scoped to the list: j/k/arrows move, Enter opens → `onOpen(item)` or follows `href`. Opening an item or clicking one of its actions marks it read. The host owns read state (`read`); the component also tracks read ids locally, so it works uncontrolled. The unread dot is announced (sr-only "Unread"). Status glyph or `Avatar`; `<time>` via `formatRelativeTime`, refreshed each minute. Empty state via `Empty` ("You're all caught up"). | `items: NotificationItem[]`, `tabs?: {id, label, filter?}[]`, `tab` (bindable), `defaultTab?`, `onTabChange?`, `onOpen?`, `onMarkRead?(ids)`, `onMarkAllRead?` (omitted → `onMarkRead` gets every unread id), `groupByDate?` (true), `now?`, `maxHeight?` ('32rem'), `title?`, `emptyTitle?`, `emptyDescription?` |
 | `ComposerGlow` | Opt-in ambient rim light around a composer while the agent works: an SVG `<rect rx>` stroke with a pathLength=100 dash laps the box in three layers (crisp line, glow, bloom clipped inside; SVG `feGaussianBlur`, so iOS stays soft); a ResizeObserver keeps the viewBox equal to the px box. Token colours only (info → primary → `color-mix` midpoint → secondary → accent). Fades in/out on `active`; the lap runs only while visible. Under `data-motion="calm"` / reduced motion there is no frozen arc: it shows a static primary focus-ring tint. Paints a `--color-base-100` surface, so the wrapped composer must be transparent. | `active`, `speed?` (4.5 s/lap), `intensity?` ('subtle'\|'normal'\|'vivid'), `radius?` (px or CSS; default box radius), `class?`, `children` |
 | `StreamedText` | Streamed assistant text revealed per paragraph/line, never per token: an append-only splitter (`splitStreamedText`, index keys, code fences kept whole) mounts each block once with a short fade + un-blur on motion tokens, after which it only grows. History doesn't animate; reduced motion is static; a subtle caret shows while `streaming`. `renderBlock` lets the host render markdown per block. Recipe: show `AgentThinking` until the first *text* part exists, not while the request status is "submitted". | `text`, `streaming?`, `split?` ('paragraph'\|'line'), `as?`, `class?`, `renderBlock?: Snippet<[string, number]>` |
+| `ChatTranscript` | Read-only, two-sided transcript of NAMED speakers — a live phone call (caller vs. the assistant's persona), a Scribe dictation, a meeting recording. Not a chat client (no composer/reactions/edit/delete, no HTML in the words; for a channel use `MessageThread`). Speakers sit on opposite sides (first listed `start`, second `end`, or `side`); consecutive turns group into a run (name + avatar once, tail on the last bubble; a grouped bubble carries the name sr-only). Label speakers by real names ("Dana Testwell", "Ruby"), never role words. `streaming` reveals the LAST turn per line through `StreamedText` with a caret. New turns slide in from their own side on motion tokens (history doesn't animate; calm/reduced motion honoured). Follows the live edge via `createStickToBottom`, `JumpToLatest` when scrolled away. Polite `role="log"`, keyboard-scrollable, `<time>` stamps (offset ms → "1:05", ISO → clock). Bubble tints are `color-mix` of a token family (`tone`: neutral/primary/secondary/accent/info). `meta` snippet (latency, flags — in words), `actions` snippet (hover/focus toolbar, none by default), `onTurnClick` (bubble becomes a button, e.g. seek) + `activeId`. Pure helpers: `buildTranscriptRows`, `resolveSpeakerSides`, `formatTurnTime`. | `turns: TranscriptTurn[]` (`{id, speaker, text \| null, at?, placeholder?}`), `speakers: TranscriptSpeaker[]` (`{id, name, side?, avatarUrl?, tone?}`), `streaming?`, `group?` (true), `avatars?` (true), `live?` (true), `follow?` (true), `ariaLabel?`, `formatTime?`, `emptyText?`, `meta?`/`actions?` (snippets), `onTurnClick?`, `activeId?`, `maxHeight?`, `class?` |
 
 **Upgrades in this wave (all additive):**
 - **`Steps`** (`progress/Steps.svelte`) — `collapsible?`, `collapsed?` (bindable), `summary?: string | Snippet` (default "3 steps left" / "All steps done", live while folded; the header is a real `aria-expanded` / `aria-controls` button), `orientation?` ('horizontal'\|'vertical'; vertical also shows descriptions), `activeProgress?` (0–1, a mini ProgressRing on the active node and in the folded header), `completionDelay?` + `onFinished?` (fires once after `current` passes the last step; re-arms if `current` drops back). Unset, the markup is unchanged. Helpers: `stepsSummary`, `stepsRemaining`, `isStepsFinished`, `clampStepProgress`.

package/dist/components/AmbienceToggle.svelte

@@ -25,6 +25,11 @@
 	 *     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`).
@@ -129,6 +134,65 @@
 		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">
@@ -190,10 +254,18 @@
 	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);
 
+	// 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);
@@ -260,9 +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. A resize
-	// closes an open submenu (its position is stale).
+	// 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;
@@ -276,12 +349,26 @@
 		const onResize = () => closeSubmenu(false);
 		document.addEventListener('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(() => {
@@ -328,6 +415,7 @@
 		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;
 	}
 
@@ -433,6 +521,74 @@
 		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;
@@ -657,7 +813,7 @@
 			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>

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

@@ -24,6 +24,11 @@
  *     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`).
@@ -91,6 +96,37 @@ export declare function placeSubmenu(row: {
     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. Section order/labels come from the engine's `groups` option. */

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;