@djangocfg/ui-tools 2.1.381 → 2.1.382

package/src/tools/SpeechRecognition/README.md

@@ -0,0 +1,336 @@
+# SpeechRecognition
+
+Decomposed Speech-to-Text for the React app. **Headless core + composable UI parts + lazy bundle**, just like [`Chat`](../Chat) and [`AudioPlayer`](../AudioPlayer).
+
+The default backend is the browser's native Web Speech API (zero deps, zero network). For anything else — Deepgram, AssemblyAI, OpenAI Whisper, your own Django/FastAPI gateway — plug a custom engine into the same hook. No SDK lock-in.
+
+```bash
+pnpm add @djangocfg/ui-tools
+```
+
+Subpath import (recommended — keeps the rest of `ui-tools` out of your bundle):
+
+```ts
+import {
+  useSpeechRecognition,
+  DictationField,
+  createWebSpeechEngine,
+  createHttpEngine,
+  createWebSocketEngine,
+} from '@djangocfg/ui-tools/speech-recognition';
+```
+
+---
+
+## Quick start
+
+```tsx
+import {
+  DictationButton,
+  TranscriptView,
+  useSpeechRecognition,
+} from '@djangocfg/ui-tools/speech-recognition';
+
+function Dictate() {
+  const rec = useSpeechRecognition();         // Web Speech engine, browser language
+  return (
+    <div className="flex items-start gap-3">
+      <DictationButton status={rec.status} onClick={() => rec.toggle()} />
+      <TranscriptView transcript={rec.transcript} />
+    </div>
+  );
+}
+```
+
+That's the whole "make me type with my voice" flow. With no config, the hook uses `createWebSpeechEngine()` and the language stored in `useSpeechPrefs` (defaults to `navigator.language`).
+
+---
+
+## DictationField — the opinionated widget
+
+A textarea + mic button + interim ghost + push-to-talk hint, all wired up. Final segments are appended to the controlled `value`.
+
+```tsx
+import { DictationField } from '@djangocfg/ui-tools/speech-recognition';
+
+const [text, setText] = useState('');
+
+<DictationField
+  value={text}
+  onChange={setText}
+  language="ru-RU"
+  pushToTalk={{ key: 'alt' }}
+  placeholder="Type or hold ⌥ to talk…"
+/>
+```
+
+For voice-memo flows there's `VoiceMessageRecorder`: press the mic, dictate freely, silence-detection or 60-second cap triggers `onSubmit(text, segments)`.
+
+---
+
+## Custom engines — the whole point
+
+`useSpeechRecognition` doesn't care **how** audio becomes text. The `RecognitionEngine` interface is small enough to implement against any backend.
+
+### HTTP (Whisper, custom REST)
+
+```ts
+import { createHttpEngine } from '@djangocfg/ui-tools/speech-recognition';
+
+const engine = createHttpEngine({
+  url: '/api/stt/transcribe',
+  headers: async () => ({ Authorization: `Bearer ${token}` }),
+  chunkMs: 750,
+  parse: async (resp) => {
+    const { text, final } = await resp.json();
+    return { text, isFinal: final };
+  },
+});
+
+const rec = useSpeechRecognition({ engine });
+```
+
+Captures audio with `MediaRecorder` (Opus/WebM by default), POSTs each chunk as the request body, runs your `parse` callback on the response.
+
+### External (Wails / Tauri / native sidecar)
+
+When the host owns the entire pipeline — capture happens outside the browser, transcription runs on the backend, the frontend just commands "start" / "stop" — use `createExternalEngine`. Perfect for cmdop's Wails whisper.cpp integration.
+
+```ts
+import { createExternalEngine } from '@djangocfg/ui-tools/speech-recognition';
+import { EventsOn } from '@runtime';
+import * as VoiceService from '@bindings/desktop/services/voice/service';
+
+const wailsEngine = createExternalEngine({
+  id: 'wails-whisper',
+  onStart: () => VoiceService.StartRecordingForChat(),
+  onStop: () => VoiceService.StopRecordingForChat(),
+  subscribe: (handle) => {
+    const offText = EventsOn('voice:chat-text', (p) => {
+      if (p?.error) handle.emitError({ code: 'engine', message: p.error });
+      else if (p?.text) handle.emitFinal(p.text);
+      else handle.emitError({ code: 'no-speech', message: '' });
+    });
+    const offState = EventsOn('voice:state', (s) => {
+      if (s.state === 'recording' || s.state === 'streaming') handle.markListening();
+      if (s.partial) handle.emitPartial(s.partial);
+    });
+    return () => { offText(); offState(); };
+  },
+});
+
+<VoiceComposerSlot engine={wailsEngine} value={composer.value} onChange={composer.setValue} />
+```
+
+No `MediaRecorder` / `getUserMedia` — the engine is purely a translator between the chat UI and your event bus. `emitFinal` automatically closes the session, so the composer reset / autosend logic fires the moment the backend posts a result.
+
+### WebSocket (Deepgram / AssemblyAI / custom realtime)
+
+```ts
+import { createWebSocketEngine } from '@djangocfg/ui-tools/speech-recognition';
+
+const engine = createWebSocketEngine({
+  url: async () => {
+    const { token } = await fetch('/api/stt/ticket').then((r) => r.json());
+    return `wss://stt.example.com/listen?token=${token}`;
+  },
+  chunkMs: 250,
+  parseMessage: (data) => {
+    if (typeof data !== 'string') return { kind: 'ignore' };
+    const msg = JSON.parse(data);
+    if (msg.type === 'Results') {
+      return msg.is_final
+        ? { kind: 'final', text: msg.channel.alternatives[0].transcript }
+        : { kind: 'partial', text: msg.channel.alternatives[0].transcript };
+    }
+    return { kind: 'ignore' };
+  },
+});
+```
+
+Reconnect with exponential backoff (250 ms → 5 s) is built in. Tokens go through a `url()` callback so they can be minted server-side and rotated per session.
+
+### Anything else
+
+Implement `RecognitionEngine` directly — on-device Whisper WASM, Picovoice, native bridges from Tauri / Electron, mocked engines for tests. The interface:
+
+```ts
+interface RecognitionEngine {
+  id: string;
+  isSupported: boolean;
+  start(opts: EngineStartOptions): Promise<void>;
+  stop(): Promise<void>;
+  abort(): void;
+  on(event, cb): Unsub;            // 'partial' | 'final' | 'error' | 'state'
+  getStream?(): MediaStream | null; // optional — for VU meters
+}
+```
+
+`createEngineBus()` gives you the listener bookkeeping in three lines.
+
+---
+
+## Voice inside the Chat composer
+
+Two drop-ins, designed to live together:
+
+```tsx
+import { ChatRoot } from '@djangocfg/ui-tools/chat';
+import {
+  ChatHeaderLanguageButton,
+  VoiceComposerSlot,
+} from '@djangocfg/ui-tools/speech-recognition';
+
+<ChatRoot
+  transport={transport}
+  composerToolbarEnd={<VoiceComposerSlot />}
+/>
+
+// Header flag-picker is added via ChatLauncher dock slot:
+<ChatLauncher dock={{ headerActions: <ChatHeaderLanguageButton /> }}>
+```
+
+That's it. No props, no refs. The slot reads / writes the composer through the `ComposerHandle` registered in `ChatProvider` (`focus / moveCursorToEnd / getValue / setValue`), so the built-in `<Composer>` and a TipTap-backed `MarkdownEditor` work the same way — host implements `useRegisterComposer({...})` once and voice flows in.
+
+What you get without writing it yourself:
+
+- **Anchored merge.** The text typed before pressing the mic is preserved; dictation is appended to that anchor.
+- **Live focus + cursor pinning.** On start, the composer is focused and the caret jumps to end; every partial / final repins the caret so the live transcript visibly grows where the user expects.
+- **Auto-hide.** `useVoiceSupport()` checks `engine.isSupported` + `getUserMedia` + browser type (Firefox / Instagram / TikTok WebViews → renders `null`).
+- **Countdown chip + tooltip.** A `useCountdownFromSeconds()` ticker (max 90 s default) sits next to the mic button.
+- **Silence stop.** Auto-stop after 2.5 s of quiet (configurable via `silenceMs`).
+- **Esc / Enter hotkeys while listening.** Esc cancels (and `stopPropagation` so the chat doesn't close), Enter finishes recording (and **does not** submit the chat — avoids accidental sends mid-sentence).
+- **Earcons.** Bundled start (low chime) + stop (short tick) reused from chat sounds, both at deliberately quiet volumes. Override via `sounds={{ start, stop }}` or disable with `sounds={false}`.
+
+The explicit `value` / `onChange` form is still supported for standalone usage outside a `<ChatProvider>`:
+
+```tsx
+<VoiceComposerSlot value={value} onChange={setValue} />
+```
+
+### Language picker — flag button in the chat header
+
+```tsx
+<ChatHeader actions={<ChatHeaderLanguageButton />} />
+```
+
+Compact 28×28 flag button. Shows the currently-resolved language's country flag (🇷🇺 for `ru-RU`, 🇺🇸 for `en-US`). Clicking opens a searchable `<Combobox>` with **66 BCP-47 tags from the official Chrome Web Speech demo** (`WEB_SPEECH_LANGUAGES` catalogue) — language name + region + tag, every row with a country flag, search across all three fields. Choice persists in `useSpeechPrefs`.
+
+### Shared state across the tree
+
+Need to react to listening state elsewhere (dim textarea, header indicator)? Wrap the chat in `<SpeechRecognitionProvider>` and read `useSpeechRecognitionContext()` from any descendant.
+
+### Reading the active language from elsewhere
+
+Speech language is **persisted independently** of the app's i18n locale (`djangocfg-stt:prefs` in localStorage). Read it from any component:
+
+```tsx
+import {
+  useSpeechPrefs,            // raw user choice — `string | null`
+  useResolvedLanguage,       // resolved BCP-47 with full fallback chain
+  useSpeechLanguageInfo,     // combo: { tag, iso, country, name, englishName, region, hasUserChoice }
+} from '@djangocfg/ui-tools/speech-recognition';
+
+function HeaderBadge() {
+  const { tag, name, country, hasUserChoice } = useSpeechLanguageInfo();
+  return (
+    <Badge>
+      <Flag countryCode={country} />
+      {name ?? tag}
+      {hasUserChoice && <span className="ml-1">★</span>}
+    </Badge>
+  );
+}
+```
+
+Push to backend on every change:
+
+```tsx
+const { tag, hasUserChoice } = useSpeechLanguageInfo();
+useEffect(() => {
+  if (!hasUserChoice) return;
+  void api.user.update({ speechLanguage: tag });
+}, [tag, hasUserChoice]);
+```
+
+Outside React (event handlers, util functions, non-component code):
+
+```ts
+import { useSpeechPrefs } from '@djangocfg/ui-tools/speech-recognition';
+const current = useSpeechPrefs.getState().language;          // 'ru-RU' | null
+const unsubscribe = useSpeechPrefs.subscribe((state) => {
+  console.log('language changed', state.language);
+});
+```
+
+---
+
+## What you get for free
+
+- **Zero-setup default** — `useSpeechRecognition()` works with no engine, no config.
+- **Permission-aware UX** — `permission-denied` / `no-microphone` / `no-speech` surface as typed errors; `<ErrorBanner>` translates them.
+- **Persisted prefs** — language, mic device, engine choice live in zustand+localStorage (`djangocfg-stt:prefs`).
+- **Auto-stop** — `autoStop: { silenceMs, maxMs, silenceThreshold }` based on RMS analyser; opt-in.
+- **Push-to-talk** — `usePushToTalk({ key: 'mod+alt' })` with smart input-field bypass.
+- **VU meter** — `useMicLevel(stream)` + `<MicMeter />` for level visualisation.
+- **Mic enumeration** — `useMicDevices()` returns `audioinput` list, refreshes on `devicechange`.
+- **Interim+final UI** — `<TranscriptView>` dims the trailing interim chunk so users see the model "thinking".
+
+---
+
+## Public surface
+
+### Hooks
+`useSpeechRecognition`, `useDictation`, `usePushToTalk`, `useMicDevices`, `useMicLevel`, `useEnginePrefs`, `useSpeechPrefs`, `useVoiceSupport`, `useResolvedLanguage`, `useSpeechLanguageInfo`.
+
+### Context
+`SpeechRecognitionProvider`, `useSpeechRecognitionContext`, `useSpeechRecognitionContextOptional` — lift a single engine instance so any descendant (composer slot, header badge, transcript overlay) sees the same `status` / `transcript` / `level`.
+
+### Components
+`DictationButton`, `MicMeter`, `TranscriptView`, `LanguagePicker`, `DevicePicker`, `EngineBadge`, `ErrorBanner`, `PushToTalkHint`. Chat header: `ChatHeaderLanguageButton` (re-exported from chat launcher).
+
+### Widgets
+`DictationField`, `VoiceMessageRecorder`, `VoiceComposerSlot`, `LazyDictationField`.
+
+### Engines
+`createWebSpeechEngine`, `createHttpEngine`, `createWebSocketEngine`, `createExternalEngine`, `createEngineBus`, `startMicCapture`, `pickMime`.
+
+### Language utilities
+`WEB_SPEECH_LANGUAGES` (catalogue of 66 supported BCP-47 tags from the Chrome demo), `WEB_SPEECH_TAGS` (flat array), `findSpeechLanguage(tag)`, `countryFromTag(tag)`, `toBCP47(iso)`, `resolveSpeechLanguage({ explicit, prefs, i18n })`, `DEFAULT_ISO_TO_BCP47`, `DEFAULT_VOICE_SOUNDS`.
+
+### Types
+`RecognitionEngine`, `RecognitionStatus`, `RecognitionError`, `RecognitionErrorCode`, `Segment`, `Transcript`, `EngineState`, `EngineStartOptions`, `EngineEventMap`, `Unsub`, `AutoStopOptions`, `VoiceSupport`, `VoiceUnsupportedReason`.
+
+---
+
+## Tests
+
+```bash
+pnpm test         # one-shot
+pnpm test:watch   # vitest watch mode
+```
+
+Covered (12 cases, all pure-function): reducer state machine (`__tests__/reducer.test.ts`), transcript merge + `normaliseFinal` (`__tests__/transcript.test.ts`), `newSegmentId` (`__tests__/ids.test.ts`). Engine adapters and UI parts rely on stories — `MediaRecorder` / `getUserMedia` / `WebSocket` are mock-engine-driven in the playground.
+
+---
+
+## Stories
+
+`Tools/SpeechRecognition/{Basic, DictationField, PushToTalk, MicMeter, CustomEngine: HTTP, CustomEngine: WebSocket, Language & Device, Errors}` plus `Tools/Chat/Voice composer` for the chat-slot integration — all driven by a deterministic mock engine so the playground never asks for microphone permission.
+
+```bash
+pnpm playground
+```
+
+---
+
+## Browser support
+
+| Browser | Default engine | Notes |
+|---|---|---|
+| Chrome / Edge desktop | ✅ Web Speech | Best — continuous + interim results. |
+| Safari 16+ desktop | ✅ Web Speech | Continuous works; some locales partial only. |
+| Firefox desktop | ❌ Web Speech | `isSupported === false`. Pass a custom engine (HTTP/WS). |
+| Mobile WebViews | ⚠️ varies | Always pair with a fallback engine in production. |
+
+For Firefox / WebView consumers: pass `engine: createHttpEngine(...)` and you're streaming again.

package/src/tools/SpeechRecognition/__tests__/ids.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, it } from 'vitest';
+
+import { newSegmentId } from '../core/ids';
+
+describe('newSegmentId', () => {
+  it('produces unique values across calls', () => {
+    const ids = new Set<string>();
+    for (let i = 0; i < 200; i += 1) ids.add(newSegmentId());
+    expect(ids.size).toBe(200);
+  });
+
+  it('matches the seg_<time>_<n> shape', () => {
+    expect(newSegmentId()).toMatch(/^seg_[a-z0-9]+_[a-z0-9]+$/);
+  });
+});

package/src/tools/SpeechRecognition/__tests__/language.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from 'vitest';
+
+import { resolveSpeechLanguage, toBCP47 } from '../core/language';
+
+describe('toBCP47', () => {
+  it('maps known ISO-2 codes to canonical BCP-47', () => {
+    expect(toBCP47('en')).toBe('en-US');
+    expect(toBCP47('ru')).toBe('ru-RU');
+    expect(toBCP47('ko')).toBe('ko-KR');
+    expect(toBCP47('pt')).toBe('pt-BR');
+    expect(toBCP47('no')).toBe('nb-NO');
+  });
+
+  it('falls back to <code>-<UPPER(code)> for unmapped ISO codes', () => {
+    expect(toBCP47('uk')).toBe('uk-UK');
+    expect(toBCP47('cs')).toBe('cs-CS');
+  });
+
+  it('passes BCP-47 input through unchanged', () => {
+    expect(toBCP47('en-GB')).toBe('en-GB');
+    expect(toBCP47('zh-TW')).toBe('zh-TW');
+  });
+
+  it('returns undefined for empty / null', () => {
+    expect(toBCP47(null)).toBeUndefined();
+    expect(toBCP47(undefined)).toBeUndefined();
+    expect(toBCP47('')).toBeUndefined();
+    expect(toBCP47('   ')).toBeUndefined();
+  });
+});
+
+describe('resolveSpeechLanguage', () => {
+  it('priority: explicit beats everything', () => {
+    expect(
+      resolveSpeechLanguage({
+        explicit: 'ko-KR',
+        prefs: 'ru-RU',
+        i18n: 'en',
+      }),
+    ).toBe('ko-KR');
+  });
+
+  it('priority: prefs beats i18n', () => {
+    expect(resolveSpeechLanguage({ prefs: 'ru-RU', i18n: 'en' })).toBe('ru-RU');
+  });
+
+  it('priority: i18n beats navigator', () => {
+    expect(resolveSpeechLanguage({ i18n: 'ru' })).toBe('ru-RU');
+  });
+
+  it('falls back to en-US when nothing supplied and no navigator', () => {
+    expect(resolveSpeechLanguage({})).toMatch(/^[a-z]{2}-[A-Z]{2}$/);
+  });
+
+  it('normalises ISO-2 in any slot', () => {
+    expect(resolveSpeechLanguage({ explicit: 'ru' })).toBe('ru-RU');
+    expect(resolveSpeechLanguage({ prefs: 'ko' })).toBe('ko-KR');
+  });
+});

package/src/tools/SpeechRecognition/__tests__/reducer.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it } from 'vitest';
+
+import { INITIAL_STATE, reducer } from '../core/reducer';
+
+describe('SpeechRecognition reducer', () => {
+  it('starts and finishes a session', () => {
+    const s1 = reducer(INITIAL_STATE, { type: 'START' });
+    expect(s1.status).toBe('starting');
+    expect(s1.startedAt).toBeTypeOf('number');
+    expect(s1.error).toBeNull();
+
+    const s2 = reducer(s1, { type: 'STARTED' });
+    expect(s2.status).toBe('listening');
+
+    const s3 = reducer(s2, { type: 'STOP' });
+    expect(s3.status).toBe('stopping');
+
+    const s4 = reducer(s3, { type: 'STOPPED' });
+    expect(s4.status).toBe('idle');
+  });
+
+  it('merges PARTIAL into an interim segment, then promotes to FINAL', () => {
+    let s = reducer(INITIAL_STATE, { type: 'START' });
+    s = reducer(s, { type: 'STARTED' });
+    s = reducer(s, { type: 'PARTIAL', text: 'hel', segmentId: 'seg-1' });
+    s = reducer(s, { type: 'PARTIAL', text: 'hello', segmentId: 'seg-1' });
+    expect(s.segments).toHaveLength(1);
+    expect(s.segments[0]).toMatchObject({
+      id: 'seg-1',
+      text: 'hello',
+      isFinal: false,
+    });
+
+    s = reducer(s, { type: 'FINAL', text: 'hello world', segmentId: 'seg-1', confidence: 0.91 });
+    expect(s.segments).toHaveLength(1);
+    expect(s.segments[0]).toMatchObject({
+      id: 'seg-1',
+      text: 'hello world',
+      isFinal: true,
+      confidence: 0.91,
+    });
+  });
+
+  it('accumulates separate segments', () => {
+    let s = reducer(INITIAL_STATE, { type: 'START' });
+    s = reducer(s, { type: 'FINAL', text: 'one', segmentId: 'a' });
+    s = reducer(s, { type: 'FINAL', text: 'two', segmentId: 'b' });
+    s = reducer(s, { type: 'PARTIAL', text: 'thr', segmentId: 'c' });
+    expect(s.segments.map((seg) => seg.text)).toEqual(['one', 'two', 'thr']);
+    expect(s.segments.map((seg) => seg.isFinal)).toEqual([true, true, false]);
+  });
+
+  it('records errors and resets cleanly', () => {
+    let s = reducer(INITIAL_STATE, { type: 'START' });
+    s = reducer(s, {
+      type: 'ERROR',
+      error: { code: 'no-speech', message: 'no speech' },
+    });
+    expect(s.status).toBe('error');
+    expect(s.error?.code).toBe('no-speech');
+
+    const reset = reducer(s, { type: 'RESET' });
+    expect(reset).toEqual(INITIAL_STATE);
+  });
+
+  it('ignores unknown actions', () => {
+    // @ts-expect-error - intentionally invalid for the default branch
+    const next = reducer(INITIAL_STATE, { type: 'NOPE' });
+    expect(next).toBe(INITIAL_STATE);
+  });
+});

package/src/tools/SpeechRecognition/__tests__/transcript.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  EMPTY_TRANSCRIPT,
+  buildTranscript,
+  joinFinal,
+  normaliseFinal,
+} from '../core/transcript';
+import type { Segment } from '../types';
+
+function seg(text: string, isFinal: boolean, id = text): Segment {
+  return { id, text, isFinal, startedAt: 0 };
+}
+
+describe('transcript helpers', () => {
+  it('joinFinal skips interim and trims whitespace', () => {
+    const out = joinFinal([
+      seg('Hello.', true, 'a'),
+      seg('  world  ', true, 'b'),
+      seg('partial', false, 'c'),
+    ]);
+    expect(out).toBe('Hello. world');
+  });
+
+  it('buildTranscript exposes trailing interim text', () => {
+    const t = buildTranscript([
+      seg('Hi.', true, 'a'),
+      seg('there', false, 'b'),
+    ]);
+    expect(t.final).toBe('Hi.');
+    expect(t.interim).toBe('there');
+    expect(t.segments).toHaveLength(2);
+  });
+
+  it('buildTranscript with only finals leaves interim empty', () => {
+    const t = buildTranscript([seg('Done.', true)]);
+    expect(t.interim).toBe('');
+    expect(t.final).toBe('Done.');
+  });
+
+  it('EMPTY_TRANSCRIPT is the zero value', () => {
+    expect(EMPTY_TRANSCRIPT.interim).toBe('');
+    expect(EMPTY_TRANSCRIPT.final).toBe('');
+    expect(EMPTY_TRANSCRIPT.segments).toEqual([]);
+  });
+
+  it('normaliseFinal collapses whitespace and fixes punctuation spacing', () => {
+    expect(normaliseFinal('  hello   world  ')).toBe('hello world');
+    expect(normaliseFinal('Hi , there !')).toBe('Hi, there!');
+    expect(normaliseFinal('one\ntwo\tthree')).toBe('one two three');
+  });
+});

package/src/tools/SpeechRecognition/components/DevicePicker.tsx

@@ -0,0 +1,49 @@
+'use client';
+
+import type * as React from 'react';
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+import type { MicDevice } from '../hooks/useMicDevices';
+
+export interface DevicePickerProps {
+  devices: MicDevice[];
+  value: string | null;
+  onChange: (id: string | null) => void;
+  className?: string;
+  disabled?: boolean;
+  defaultLabel?: string;
+  ariaLabel?: string;
+}
+
+export function DevicePicker({
+  devices,
+  value,
+  onChange,
+  className,
+  disabled,
+  defaultLabel = 'System default',
+  ariaLabel = 'Microphone',
+}: DevicePickerProps): React.ReactElement {
+  return (
+    <select
+      value={value ?? ''}
+      onChange={(e) => onChange(e.target.value || null)}
+      disabled={disabled}
+      aria-label={ariaLabel}
+      className={cn(
+        'h-8 rounded-md border border-input bg-background px-2 text-xs text-foreground',
+        'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+        'disabled:cursor-not-allowed disabled:opacity-50',
+        className,
+      )}
+    >
+      <option value="">{defaultLabel}</option>
+      {devices.map((d) => (
+        <option key={d.deviceId} value={d.deviceId}>
+          {d.label}
+        </option>
+      ))}
+    </select>
+  );
+}

package/src/tools/SpeechRecognition/components/DictationButton.tsx

@@ -0,0 +1,93 @@
+'use client';
+
+import type * as React from 'react';
+
+import { Loader2, Mic, MicOff } from 'lucide-react';
+import type { CSSProperties, ReactNode } from 'react';
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+import type { RecognitionStatus } from '../types';
+
+export interface DictationButtonProps {
+  status: RecognitionStatus;
+  onClick: () => void;
+  isSupported?: boolean;
+  size?: 'sm' | 'md' | 'lg';
+  className?: string;
+  style?: CSSProperties;
+  ariaLabel?: string;
+  /** Override icon for the idle state. */
+  idleIcon?: ReactNode;
+  /** Override icon for the listening state. */
+  listeningIcon?: ReactNode;
+  /** Disable without unmounting. */
+  disabled?: boolean;
+}
+
+const SIZE_CLS: Record<NonNullable<DictationButtonProps['size']>, string> = {
+  sm: 'h-8 w-8 [&_svg]:h-4 [&_svg]:w-4',
+  md: 'h-10 w-10 [&_svg]:h-5 [&_svg]:w-5',
+  lg: 'h-12 w-12 [&_svg]:h-6 [&_svg]:w-6',
+};
+
+/**
+ * Round microphone button. Cycles icon by status; shows a soft pulse
+ * ring when listening. ARIA-correct so screen readers announce
+ * "recording" vs "start dictation".
+ */
+export function DictationButton({
+  status,
+  onClick,
+  isSupported = true,
+  size = 'md',
+  className,
+  style,
+  ariaLabel,
+  idleIcon,
+  listeningIcon,
+  disabled,
+}: DictationButtonProps): React.ReactElement {
+  const listening = status === 'listening' || status === 'starting';
+  const stopping = status === 'stopping';
+  const off = !isSupported;
+
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      disabled={disabled || off}
+      aria-pressed={listening}
+      aria-label={
+        ariaLabel ?? (listening ? 'Stop dictation' : off ? 'Dictation not supported' : 'Start dictation')
+      }
+      className={cn(
+        'relative inline-flex items-center justify-center rounded-full transition-colors',
+        'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2',
+        'disabled:cursor-not-allowed disabled:opacity-50',
+        SIZE_CLS[size],
+        listening
+          ? 'bg-destructive text-destructive-foreground hover:bg-destructive/90'
+          : 'bg-primary text-primary-foreground hover:bg-primary/90',
+        className,
+      )}
+      style={style}
+    >
+      {listening && (
+        <span
+          aria-hidden
+          className="absolute inset-0 rounded-full bg-destructive/40 animate-ping"
+        />
+      )}
+      {stopping ? (
+        <Loader2 className="animate-spin" />
+      ) : off ? (
+        listeningIcon ?? <MicOff />
+      ) : listening ? (
+        listeningIcon ?? <Mic />
+      ) : (
+        idleIcon ?? <Mic />
+      )}
+    </button>
+  );
+}