@joewinke/jatui 0.22.0 → 0.24.0

package/dist/components/AudioRecorder.svelte

@@ -0,0 +1,529 @@
+<script module lang="ts">
+	// The capture pipeline lives in the headless factory (jatui-is2ow.8) —
+	// this component is its markup. Re-exported here so consumers importing
+	// the type from the component keep working.
+	export type { AudioRecordingResult } from '../utils/audioRecorderCore'
+
+	/** m:ss zero-padded seconds — shared format for the timer display. */
+	export function formatDuration(totalSeconds: number): string {
+		const mins = Math.floor(totalSeconds / 60)
+		const secs = Math.floor(totalSeconds % 60)
+		return `${mins}:${secs.toString().padStart(2, '0')}`
+	}
+
+	/** 1.2 KB / 3.4 MB style byte formatting for the size readout. */
+	export function formatFileSize(bytes: number): string {
+		if (bytes <= 0) return '0 B'
+		const k = 1024
+		const sizes = ['B', 'KB', 'MB', 'GB']
+		const i = Math.min(Math.floor(Math.log(bytes) / Math.log(k)), sizes.length - 1)
+		return `${parseFloat((bytes / Math.pow(k, i)).toFixed(1))} ${sizes[i]}`
+	}
+</script>
+
+<script lang="ts">
+	/**
+	 * AudioRecorder — voice-memo recorder with live waveform, ported from
+	 * chimaro's chat/AudioRecorder.svelte (jatui-m4uz3.5).
+	 *
+	 * Completes jatui's audio trio alongside AudioWaveform (playback) and
+	 * SpeechForm (voice-to-text input): this one is the CAPTURE surface.
+	 *
+	 * Ported as a host-agnostic primitive — everything chimaro-specific is
+	 * decoupled into emitted callbacks:
+	 *   • no promptStore — the custom-prompt textarea was host state, not
+	 *     recorder state, and lives with the host;
+	 *   • no debugConfig — console chatter replaced by callback props;
+	 *   • no supabase template loading / analysis panel — hosts that want
+	 *     post-recording transcription or analysis consume `onRecordStop`'s
+	 *     blob payload and run their own pipeline (MardukOS Scribe does).
+	 *
+	 * What it owns: markup only — the theme-aware canvas waveform + level
+	 * meter, phase badges, and size/duration readouts. The capture pipeline
+	 * itself (permission requests, MIME negotiation, the
+	 * record/pause/resume/stop/cancel state machine, timing) lives in the
+	 * headless createAudioRecorder() factory (jatui-is2ow.8) so hosts can
+	 * drive the same pipeline from their own UI.
+	 */
+	import { onDestroy, onMount } from 'svelte'
+	import { createAudioRecorder } from '../utils/audioRecorder'
+	import { getDaisyUIColor, watchThemeChanges } from '../utils/daisyuiColors'
+	import MediaCaptureIcon from './MediaCaptureIcon.svelte'
+
+	interface Props {
+		/** `small` — inline chat-style pill (default). `large` — full recorder panel with waveform canvas. */
+		variant?: 'small' | 'large'
+		/** Auto-stop ceiling in ms. 0 (default) records until stopped manually. */
+		maxDurationMs?: number
+		disabled?: boolean
+		/** Fired once the mic stream is live and recording has started. */
+		onRecordStart?: () => void
+		onRecordPause?: () => void
+		onRecordResume?: () => void
+		/** Fired with the finished recording. May return a Promise — the
+		 * component stays in "processing" until it settles, so hosts can
+		 * upload/transcribe without the user re-triggering a recording. */
+		onRecordStop?: (result: AudioRecordingResult) => void | Promise<void>
+		/** Fired when the user cancels — no blob is produced. */
+		onRecordCancel?: () => void
+		/** Fired on recorder errors (permission denied, no mic, start failure). */
+		onError?: (message: string) => void
+		class?: string
+	}
+
+	let {
+		variant = 'small',
+		maxDurationMs = 0,
+		disabled = false,
+		onRecordStart,
+		onRecordPause,
+		onRecordResume,
+		onRecordStop,
+		onRecordCancel,
+		onError,
+		class: className = ''
+	}: Props = $props()
+
+	type Phase = 'idle' | 'starting' | 'recording' | 'processing' | 'done'
+
+	let permissionDenied = $state(false)
+
+	// Headless capture core — all media handling, timing and state live there.
+	const rec = createAudioRecorder({
+		mode: 'toggle',
+		maxDurationMs,
+		onStart: onRecordStart,
+		onPause: onRecordPause,
+		onResume: onRecordResume,
+		onStop: onRecordStop,
+		onCancel: onRecordCancel,
+		onError: (err) => {
+			if (err.kind === 'denied') permissionDenied = true
+			onError?.(err.message)
+		},
+		// Canvas visualization — driven by the core's analyser frames.
+		onFrame: ({ frequency }) => {
+			if (!canvas) return
+			if (!canvasCtx) canvasCtx = canvas.getContext('2d')
+			sizeCanvasIfNeeded()
+			if (frequency.some((v) => v > 0)) drawWaveform(frequency)
+			else {
+				clearCanvas()
+				drawIdleDots()
+			}
+		}
+	})
+
+	const phase = $derived<Phase>(rec.phase)
+	const paused = $derived(rec.paused)
+	const elapsedSec = $derived(Math.floor(rec.elapsedMs / 1000))
+	const sizeBytes = $derived(rec.sizeBytes)
+	const audioLevel = $derived(rec.level)
+	const errorMessage = $derived(rec.error?.message ?? '')
+	const supported = $derived(rec.supported)
+
+	// Canvas
+	let canvas = $state<HTMLCanvasElement | null>(null)
+	let canvasCtx: CanvasRenderingContext2D | null = null
+	let canvasColors = { background: '', centerLine: '', primary: '', secondary: '', dots: '' }
+
+	function resolveColor(name: string, fallback: string): string {
+		if (typeof window === 'undefined') return fallback
+		try {
+			const c = getDaisyUIColor(name)
+			return c && c !== 'undefined' && c !== '' ? c : fallback
+		} catch {
+			return fallback
+		}
+	}
+
+	function updateCanvasColors() {
+		canvasColors = {
+			background: resolveColor('base-200', '#1f2937'),
+			centerLine: resolveColor('base-300', '#374151'),
+			primary: resolveColor('primary', '#3b82f6'),
+			secondary: resolveColor('success', '#10b981'),
+			dots: resolveColor('base-content', '#6b7280')
+		}
+	}
+
+	function sizeCanvas() {
+		if (!canvas) return
+		const parent = canvas.parentElement
+		const width = Math.max(160, Math.min(parent?.clientWidth ?? 480, 800))
+		const height = 80
+		if (canvas.width !== width || canvas.height !== height) {
+			canvas.width = width
+			canvas.height = height
+		}
+		clearCanvas()
+	}
+
+	function clearCanvas() {
+		if (!canvas || !canvasCtx) return
+		const { width, height } = canvas
+		canvasCtx.clearRect(0, 0, width, height)
+		canvasCtx.fillStyle = canvasColors.background
+		canvasCtx.fillRect(0, 0, width, height)
+		canvasCtx.strokeStyle = canvasColors.centerLine
+		canvasCtx.lineWidth = 1
+		canvasCtx.beginPath()
+		canvasCtx.moveTo(0, height / 2)
+		canvasCtx.lineTo(width, height / 2)
+		canvasCtx.stroke()
+	}
+
+	function drawIdleDots() {
+		if (!canvas || !canvasCtx) return
+		const { width, height } = canvas
+		const count = Math.floor(width / 20)
+		const spacing = width / (count + 1)
+		const t = Date.now() * 0.003
+		canvasCtx.fillStyle = canvasColors.dots
+		for (let i = 0; i < count; i++) {
+			const pulse = Math.sin(t + i * 0.5) * 0.3 + 0.7
+			canvasCtx.beginPath()
+			canvasCtx.arc((i + 1) * spacing, height / 2, 1.5 * pulse, 0, Math.PI * 2)
+			canvasCtx.fill()
+		}
+	}
+
+	function drawWaveform(freq: Uint8Array) {
+		if (!canvas || !canvasCtx) return
+		const { width, height } = canvas
+		canvasCtx.fillStyle = canvasColors.background
+		canvasCtx.fillRect(0, 0, width, height)
+		canvasCtx.strokeStyle = canvasColors.centerLine
+		canvasCtx.lineWidth = 1
+		canvasCtx.beginPath()
+		canvasCtx.moveTo(0, height / 2)
+		canvasCtx.lineTo(width, height / 2)
+		canvasCtx.stroke()
+
+		const barCount = 60
+		const gap = 1
+		const barWidth = Math.max(1, Math.floor((width - (barCount - 1) * gap) / barCount))
+		const centerY = height / 2
+		const usable = Math.floor(freq.length * 0.75)
+		const perBar = Math.max(1, Math.floor(usable / barCount))
+
+		const gradient = canvasCtx.createLinearGradient(0, 0, 0, height)
+		gradient.addColorStop(0, canvasColors.primary)
+		gradient.addColorStop(0.5, canvasColors.secondary)
+		gradient.addColorStop(1, canvasColors.primary)
+		canvasCtx.fillStyle = gradient
+
+		for (let i = 0; i < barCount; i++) {
+			let sum = 0
+			for (let j = 0; j < perBar; j++) {
+				const idx = i * perBar + j
+				if (idx < usable) sum += freq[idx]
+			}
+			const amplified = (sum / perBar / 255) * 1.5
+			const h = Math.max(amplified * (height / 2 - 2), 0.5)
+			canvasCtx.fillRect(i * (barWidth + gap), centerY - h, barWidth, h * 2)
+		}
+	}
+
+	let lastCanvasWidth = 0
+	/** Re-measure the canvas when its container resizes, without churning every frame. */
+	function sizeCanvasIfNeeded() {
+		if (!canvas || !canvas.parentElement) return
+		const w = Math.max(160, Math.min(canvas.parentElement.clientWidth, 800))
+		if (w !== lastCanvasWidth) {
+			lastCanvasWidth = w
+			sizeCanvas()
+		}
+	}
+
+	function start() {
+		// Parity with the pre-factory guard: start is allowed from idle AND done
+		// (re-record without reset); the core guards starting/recording/processing.
+		if (disabled || phase === 'starting' || phase === 'recording' || phase === 'processing') return
+		updateCanvasColors()
+		void rec.start()
+	}
+
+	function pause() {
+		rec.pause()
+	}
+
+	function resume() {
+		rec.resume()
+	}
+
+	function stop() {
+		rec.stop()
+	}
+
+	function cancel() {
+		rec.cancel()
+	}
+
+	/** Return a finished/errored recorder to idle so the host can record again. */
+	export function reset() {
+		rec.reset()
+		permissionDenied = false
+	}
+
+	function retryAfterError() {
+		reset()
+	}
+
+	onMount(() => {
+		updateCanvasColors()
+		const unwatch = watchThemeChanges(() => {
+			updateCanvasColors()
+			clearCanvas()
+		})
+		const onResize = () => {
+			lastCanvasWidth = 0
+			if (canvas) sizeCanvas()
+		}
+		window.addEventListener('resize', onResize)
+		return () => {
+			window.removeEventListener('resize', onResize)
+			unwatch()
+		}
+	})
+
+	// While paused the core stops its frame pump — draw the idle dots instead.
+	$effect(() => {
+		if (phase === 'recording' && paused && canvas) {
+			if (!canvasCtx) canvasCtx = canvas.getContext('2d')
+			sizeCanvasIfNeeded()
+			clearCanvas()
+			drawIdleDots()
+		}
+	})
+
+	// Space toggles pause/resume while recording (chimaro behaviour).
+	function handleKeydown(e: KeyboardEvent) {
+		if (e.code === 'Space' && phase === 'recording' && variant === 'large') {
+			e.preventDefault()
+			if (paused) resume()
+			else pause()
+		}
+	}
+
+	onDestroy(() => {
+		rec.destroy()
+	})
+</script>
+
+<svelte:document onkeydown={handleKeydown} />
+
+<div class={className}>
+	{#if variant === 'large'}
+		<div class="flex flex-col items-center gap-3">
+			{#if phase === 'processing'}
+				<div class="badge badge-primary badge-lg gap-2">
+					<span class="loading loading-spinner loading-xs"></span>
+					Processing…
+				</div>
+			{:else if phase === 'done'}
+				<div class="badge badge-success badge-lg">✓ Complete</div>
+			{:else if phase === 'starting'}
+				<div class="badge badge-neutral badge-lg gap-2">
+					<span class="loading loading-spinner loading-xs"></span>
+					Preparing…
+				</div>
+			{:else if phase === 'recording' && paused}
+				<div class="badge badge-warning badge-lg">⏸ Paused</div>
+			{:else if phase === 'recording'}
+				<div class="badge badge-error badge-lg animate-pulse">● Recording</div>
+			{:else}
+				<div class="badge badge-neutral badge-lg">Ready to Record</div>
+			{/if}
+
+			{#if phase === 'recording' || phase === 'processing'}
+				<div class="font-mono text-5xl font-bold">{formatDuration(elapsedSec)}</div>
+				<div class="text-base-content/60 font-mono text-sm">{formatFileSize(sizeBytes)}</div>
+			{/if}
+
+			{#if phase === 'recording'}
+				<div class="relative flex min-h-[96px] items-center justify-center">
+					{#if !paused}
+						<div class="audio-recorder-pulse"></div>
+					{/if}
+					<canvas bind:this={canvas} class="border-base-300 bg-base-100 z-10 rounded border"></canvas>
+				</div>
+				<div class="flex min-h-[20px] items-center gap-2">
+					<span class="text-base-content/60 text-xs">Volume:</span>
+					<div class="bg-base-300 h-1 w-16 overflow-hidden rounded-full">
+						<div
+							class="h-full rounded-full bg-gradient-to-r from-success via-warning to-error"
+							style="width: {Math.min(audioLevel, 100)}%"
+						></div>
+					</div>
+				</div>
+				<div class="mt-2 flex items-center gap-3">
+					{#if paused}
+						<button
+							type="button"
+							class="btn btn-success btn-circle"
+							onclick={resume}
+							aria-label="Resume recording"
+						>
+							<MediaCaptureIcon name="play" size={20} class="fill-current" />
+						</button>
+					{:else}
+						<button
+							type="button"
+							class="btn btn-warning btn-circle"
+							onclick={pause}
+							aria-label="Pause recording"
+						>
+							<MediaCaptureIcon name="pause" size={20} />
+						</button>
+					{/if}
+					<button
+						type="button"
+						class="btn btn-primary btn-circle"
+						onclick={stop}
+						aria-label="Stop and save recording"
+					>
+						<MediaCaptureIcon name="square" size={20} class="fill-current" />
+					</button>
+				</div>
+				<button type="button" class="btn btn-ghost btn-sm text-error" onclick={cancel}>
+					<MediaCaptureIcon name="x" size={12} />
+					Cancel
+				</button>
+				<p class="text-base-content/45 text-xs">Space pauses / resumes</p>
+			{:else if phase === 'idle'}
+				<button
+					type="button"
+					class="btn btn-error btn-circle btn-xl hover:btn-primary transition-all"
+					{disabled}
+					onclick={start}
+					aria-label="Start voice recording"
+				>
+					<MediaCaptureIcon name="mic" size={24} />
+				</button>
+			{/if}
+
+			{#if errorMessage}
+				<div class="alert alert-warning w-full max-w-md text-sm" role="status" aria-live="polite">
+					<span>{errorMessage}</span>
+					{#if phase === 'idle'}
+						<button type="button" class="btn btn-xs" onclick={retryAfterError}>Dismiss</button>
+					{/if}
+				</div>
+			{/if}
+			{#if permissionDenied}
+				<p class="text-base-content/50 max-w-md text-center text-xs">
+					Your browser blocked microphone access. Enable it from the lock icon in the address bar
+					(or site settings), then press the record button again.
+				</p>
+			{/if}
+		</div>
+	{:else}
+		<!-- small: chat-inline pill -->
+		<div class="flex items-center gap-2">
+			{#if phase === 'idle'}
+				{#if supported}
+					<button
+						type="button"
+						class="btn btn-ghost btn-circle btn-sm hover:btn-primary transition-all"
+						{disabled}
+						onclick={start}
+						aria-label="Start voice recording"
+						title="Start voice recording"
+					>
+						<MediaCaptureIcon name="mic" size={14} />
+					</button>
+				{/if}
+			{:else if phase === 'starting'}
+				<div class="flex items-center gap-2" role="status" aria-live="polite">
+					<span class="loading loading-spinner loading-xs"></span>
+					<span class="text-base-content/60 text-xs">Preparing…</span>
+				</div>
+			{:else if phase === 'recording'}
+				<div class="bg-base-100 border-base-200 flex items-center gap-2 rounded-lg border p-1.5 shadow-sm">
+					{#if paused}
+						<button
+							type="button"
+							class="btn btn-success btn-circle btn-sm"
+							onclick={resume}
+							aria-label="Resume recording"
+						>
+							<MediaCaptureIcon name="play" size={14} class="fill-current" />
+						</button>
+					{:else}
+						<button
+							type="button"
+							class="btn btn-warning btn-circle btn-sm"
+							onclick={pause}
+							aria-label="Pause recording"
+						>
+							<MediaCaptureIcon name="pause" size={14} />
+						</button>
+					{/if}
+					<button
+						type="button"
+						class="btn btn-primary btn-circle btn-sm"
+						onclick={stop}
+						aria-label="Stop and save recording"
+					>
+						<MediaCaptureIcon name="square" size={14} class="fill-current" />
+					</button>
+					<span class="text-base-content/60 w-9 text-center font-mono text-xs">
+						{formatDuration(elapsedSec)}
+					</span>
+					<div class="bg-base-300 h-1 w-8 overflow-hidden rounded-full">
+						<div
+							class="h-full rounded-full bg-gradient-to-r from-success via-warning to-error"
+							style="width: {Math.min(audioLevel, 100)}%"
+						></div>
+					</div>
+					<button
+						type="button"
+						class="btn btn-ghost btn-xs text-error"
+						onclick={cancel}
+						aria-label="Cancel recording"
+					>
+						<MediaCaptureIcon name="x" size={10} />
+					</button>
+				</div>
+			{:else if phase === 'processing'}
+				<div class="flex items-center gap-2" role="status" aria-live="polite">
+					<MediaCaptureIcon name="loader" size={14} class="animate-spin" />
+					<span class="text-base-content/60 text-xs">Processing…</span>
+				</div>
+			{:else if phase === 'done'}
+				<span class="text-success text-xs">✓ Saved</span>
+				<button type="button" class="btn btn-ghost btn-xs" onclick={reset}>Record again</button>
+			{/if}
+			{#if errorMessage && variant === 'small'}
+				<span class="text-warning text-xs" role="status" aria-live="polite">{errorMessage}</span>
+			{/if}
+		</div>
+	{/if}
+</div>
+
+<style>
+	.audio-recorder-pulse {
+		position: absolute;
+		inset: -8px;
+		border-radius: 12px;
+		background: color-mix(in oklch, var(--color-error) 10%, transparent);
+		animation: audio-recorder-pulse 2s ease-in-out infinite;
+	}
+	@keyframes audio-recorder-pulse {
+		0%,
+		100% {
+			transform: scale(1);
+			opacity: 0.3;
+		}
+		50% {
+			transform: scale(1.05);
+			opacity: 0.6;
+		}
+	}
+	@media (prefers-reduced-motion: reduce) {
+		.audio-recorder-pulse {
+			animation: none;
+		}
+	}
+</style>

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

@@ -0,0 +1,30 @@
+export type { AudioRecordingResult } from '../utils/audioRecorderCore';
+/** m:ss zero-padded seconds — shared format for the timer display. */
+export declare function formatDuration(totalSeconds: number): string;
+/** 1.2 KB / 3.4 MB style byte formatting for the size readout. */
+export declare function formatFileSize(bytes: number): string;
+interface Props {
+    /** `small` — inline chat-style pill (default). `large` — full recorder panel with waveform canvas. */
+    variant?: 'small' | 'large';
+    /** Auto-stop ceiling in ms. 0 (default) records until stopped manually. */
+    maxDurationMs?: number;
+    disabled?: boolean;
+    /** Fired once the mic stream is live and recording has started. */
+    onRecordStart?: () => void;
+    onRecordPause?: () => void;
+    onRecordResume?: () => void;
+    /** Fired with the finished recording. May return a Promise — the
+     * component stays in "processing" until it settles, so hosts can
+     * upload/transcribe without the user re-triggering a recording. */
+    onRecordStop?: (result: AudioRecordingResult) => void | Promise<void>;
+    /** Fired when the user cancels — no blob is produced. */
+    onRecordCancel?: () => void;
+    /** Fired on recorder errors (permission denied, no mic, start failure). */
+    onError?: (message: string) => void;
+    class?: string;
+}
+declare const AudioRecorder: import("svelte").Component<Props, {
+    reset: () => void;
+}, "">;
+type AudioRecorder = ReturnType<typeof AudioRecorder>;
+export default AudioRecorder;

package/dist/components/BulkActionBar.svelte

@@ -14,6 +14,16 @@
 	 * shape as flat actions. Flat + grouped can be mixed; flat actions
 	 * render first, then grouped dropdowns.
 	 *
+	 * Per-action single-key hotkeys: give a flat action a one-character
+	 * `key` (e.g. `'c'`) and the component registers a window keydown
+	 * handler that fires `onSelect` for it while the bar is visible and not
+	 * loading — ignored while the focus is in a text entry target (shared
+	 * `isTypingTarget`), for modifier combos and for non-printable keys.
+	 * The key also renders as a `<kbd>` hint on the button.
+	 *
+	 * While `loadingMessage` is set, the buttons are replaced by a spinner +
+	 * message row (matches the IDE's BulkActionBar fork).
+	 *
 	 * Usage — flat only:
 	 *
 	 *     const nav = listNav({ selectable: true });
@@ -43,12 +53,18 @@
 	 */
 
 	import FloatingActionBar from './FloatingActionBar.svelte';
+	import { matchBulkHotkey } from './bulkActionBarKeys';
 	import type { ActionButton, ActionDropdown } from './FloatingActionBar.svelte';
 
 	export interface BulkAction {
 		label: string;
 		/** Optional SVG path string for a 24×24 icon. */
 		icon?: string;
+		/** Optional single-key hotkey (e.g. `'c'`) — fires `onSelect` while the
+		 * bar is visible and not loading. Ignored while typing (isTypingTarget),
+		 * for modifier combos and for non-printable keys. Rendered as a <kbd>
+		 * hint on the button. */
+		key?: string;
 		/** Called when the action is clicked. */
 		onSelect: () => void;
 		/** Renders in the danger variant. Default false. */
@@ -85,6 +101,10 @@
 		onClear?: () => void;
 		/** Loading state — disables all actions and shows a spinner. */
 		loading?: boolean;
+		/** When set, replaces the action buttons with a spinner + this message
+		 * (role="status", aria-live="polite") — the "bulk action in flight"
+		 * presentation from the IDE's fork. */
+		loadingMessage?: string | null;
 		/** Label for the count. Default "selected". */
 		countLabel?: string;
 	}
@@ -95,6 +115,7 @@
 		groups = [],
 		onClear,
 		loading = false,
+		loadingMessage = null,
 		countLabel = 'selected',
 	}: Props = $props();
 
@@ -111,11 +132,29 @@
 			id: a.id ?? a.label,
 			label: a.label,
 			icon: a.icon,
+			key: a.key,
 			variant: a.variant ?? (a.destructive ? 'danger' : 'default'),
 			onclick: a.onSelect,
 		})),
 	);
 
+	// Single-key hotkeys: fire the matching action's onSelect while the bar
+	// is visible and idle. Deciding logic is the pure matchBulkHotkey —
+	// typing targets, modifier combos and non-printable keys never fire.
+	$effect(() => {
+		if (count === 0 || loading || loadingMessage) return;
+		const hotkeyed = actions.filter((a) => a.key);
+		if (hotkeyed.length === 0) return;
+		function onKeydown(event: KeyboardEvent) {
+			const action = matchBulkHotkey(event, hotkeyed);
+			if (!action) return;
+			event.preventDefault();
+			action.onSelect();
+		}
+		window.addEventListener('keydown', onKeydown);
+		return () => window.removeEventListener('keydown', onKeydown);
+	});
+
 	const mappedDropdowns = $derived<ActionDropdown[]>(
 		groups.map((g) => ({
 			id: g.id ?? g.label,
@@ -135,6 +174,7 @@
 	actions={mapped}
 	dropdowns={mappedDropdowns}
 	{loading}
+	{loadingMessage}
 	{onClear}
 	{countLabel}
 />

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

@@ -3,6 +3,11 @@ export interface BulkAction {
     label: string;
     /** Optional SVG path string for a 24×24 icon. */
     icon?: string;
+    /** Optional single-key hotkey (e.g. `'c'`) — fires `onSelect` while the
+     * bar is visible and not loading. Ignored while typing (isTypingTarget),
+     * for modifier combos and for non-printable keys. Rendered as a <kbd>
+     * hint on the button. */
+    key?: string;
     /** Called when the action is clicked. */
     onSelect: () => void;
     /** Renders in the danger variant. Default false. */
@@ -37,6 +42,10 @@ interface Props {
     onClear?: () => void;
     /** Loading state — disables all actions and shows a spinner. */
     loading?: boolean;
+    /** When set, replaces the action buttons with a spinner + this message
+     * (role="status", aria-live="polite") — the "bulk action in flight"
+     * presentation from the IDE's fork. */
+    loadingMessage?: string | null;
     /** Label for the count. Default "selected". */
     countLabel?: string;
 }