@djangocfg/ui-tools 2.1.381 → 2.1.382

package/src/tools/SpeechRecognition/core/ids.ts

@@ -0,0 +1,11 @@
+let counter = 0;
+
+/**
+ * Cheap monotonic id — collisions are fine across sessions, we just need
+ * uniqueness within one component lifecycle. Avoids pulling in nanoid for
+ * a tool that already keeps the lazy chunk small.
+ */
+export function newSegmentId(): string {
+  counter = (counter + 1) % Number.MAX_SAFE_INTEGER;
+  return `seg_${Date.now().toString(36)}_${counter.toString(36)}`;
+}

package/src/tools/SpeechRecognition/core/index.ts

@@ -0,0 +1,14 @@
+export { newSegmentId } from './ids';
+export { sttLogger } from './logger';
+export {
+  EMPTY_TRANSCRIPT,
+  buildTranscript,
+  joinFinal,
+  normaliseFinal,
+} from './transcript';
+export {
+  INITIAL_STATE,
+  reducer,
+  type RecognitionAction,
+  type RecognitionState,
+} from './reducer';

package/src/tools/SpeechRecognition/core/language.ts

@@ -0,0 +1,78 @@
+/**
+ * Maps 2-letter ISO 639-1 codes (`en`, `ru`, `ko` — what
+ * `@djangocfg/i18n` exposes via `useLocale()`) to BCP-47 tags
+ * (`en-US`, `ru-RU`, `ko-KR`) that the Web Speech API and most cloud
+ * STT services expect.
+ *
+ * We keep a small built-in table for the locales we ship translations
+ * for; everything else falls through to `<code>-<UPPER(code)>`, which
+ * works for the majority of regions. The mapping is also re-exported
+ * so consumers can extend it.
+ */
+
+const ISO_TO_BCP47: Record<string, string> = {
+  en: 'en-US',
+  ru: 'ru-RU',
+  ko: 'ko-KR',
+  ja: 'ja-JP',
+  zh: 'zh-CN',
+  de: 'de-DE',
+  fr: 'fr-FR',
+  it: 'it-IT',
+  es: 'es-ES',
+  nl: 'nl-NL',
+  ar: 'ar-SA',
+  tr: 'tr-TR',
+  pl: 'pl-PL',
+  sv: 'sv-SE',
+  no: 'nb-NO',
+  da: 'da-DK',
+  pt: 'pt-BR',
+};
+
+export const DEFAULT_ISO_TO_BCP47 = ISO_TO_BCP47;
+
+/**
+ * Normalise any of:
+ *   - BCP-47 ("en-US", "ru-RU") — passed through.
+ *   - ISO 639-1 ("en", "ru")    — mapped via the table above, or
+ *                                 falls back to `<code>-<UPPER(code)>`.
+ *   - `null`/`undefined`/empty  — returns `undefined`.
+ */
+export function toBCP47(
+  code: string | null | undefined,
+  table: Record<string, string> = ISO_TO_BCP47,
+): string | undefined {
+  if (!code) return undefined;
+  const trimmed = code.trim();
+  if (!trimmed) return undefined;
+  if (trimmed.includes('-')) return trimmed; // already BCP-47
+  const lower = trimmed.toLowerCase();
+  return table[lower] ?? `${lower}-${lower.toUpperCase()}`;
+}
+
+/**
+ * Resolve the language tag for a speech session in priority order:
+ *   1. `explicit` prop (always wins) — host-supplied override.
+ *   2. `prefs`    — value stored in `useSpeechPrefs` (user picked it
+ *                   via `<LanguagePicker>` or programmatically).
+ *   3. `i18n`     — current i18n locale (2-letter ISO).
+ *   4. `navigator.language` — browser default.
+ *   5. `'en-US'`  — last-resort safety net.
+ *
+ * All inputs may be ISO-2 or BCP-47; the function normalises before
+ * returning.
+ */
+export function resolveSpeechLanguage(opts: {
+  explicit?: string;
+  prefs?: string | null;
+  i18n?: string | null;
+}): string {
+  return (
+    toBCP47(opts.explicit) ??
+    toBCP47(opts.prefs) ??
+    toBCP47(opts.i18n) ??
+    toBCP47(typeof navigator !== 'undefined' ? navigator.language : null) ??
+    'en-US'
+  );
+}

package/src/tools/SpeechRecognition/core/languages-catalog.ts

@@ -0,0 +1,229 @@
+/**
+ * Canonical list of BCP-47 language tags that the browser Web Speech
+ * API is known to accept. Sourced from the official Google Chrome
+ * Speech API demo (`google.com/intl/en/chrome/demos/speech.html`),
+ * which is the de-facto reference — the spec itself doesn't expose a
+ * way to enumerate supported languages, so this list is the
+ * best-effort guarantee for what works in Chromium-based browsers.
+ *
+ * Each entry groups one human-readable language with its dialect
+ * variants. The default tag (first in `dialects`) is what `lang` is
+ * set to when the user picks the language without a regional dialect.
+ *
+ * For custom engines (cmdop wails-whisper, Deepgram, …) hosts can
+ * pass their own subset via the `availableLanguages` prop on the
+ * picker — backend may support more or fewer tags than the browser.
+ */
+
+export interface SpeechLanguageDialect {
+  /** BCP-47 tag (e.g. `en-US`). */
+  code: string;
+  /** Region label in the language's native script (e.g. "United States"). */
+  region: string;
+}
+
+export interface SpeechLanguage {
+  /** Native-script name (e.g. "Русский", "中文"). */
+  name: string;
+  /**
+   * English name used as a secondary search key so users typing
+   * "russian" / "chinese" / "korean" land on the right row regardless
+   * of the native script. Always lowercase.
+   */
+  englishName: string;
+  /**
+   * Primary-subtag ISO-639 code (e.g. `en`, `ru`, `cmn`). Used as the
+   * map key into the `LanguageSelect` ui-core component.
+   */
+  iso: string;
+  /** One or more region dialects. Length >= 1. */
+  dialects: SpeechLanguageDialect[];
+}
+
+export const WEB_SPEECH_LANGUAGES: SpeechLanguage[] = [
+  { name: 'Afrikaans', iso: 'af', englishName: 'afrikaans', dialects: [{ code: 'af-ZA', region: 'South Africa' }] },
+  { name: 'አማርኛ', iso: 'am', englishName: 'amharic', dialects: [{ code: 'am-ET', region: 'Ethiopia' }] },
+  { name: 'Azərbaycanca', iso: 'az', englishName: 'azerbaijani', dialects: [{ code: 'az-AZ', region: 'Azerbaijan' }] },
+  {
+    name: 'বাংলা', iso: 'bn', englishName: 'bengali',
+    dialects: [
+      { code: 'bn-BD', region: 'Bangladesh' },
+      { code: 'bn-IN', region: 'India' },
+    ],
+  },
+  { name: 'Bahasa Indonesia', iso: 'id', englishName: 'indonesian', dialects: [{ code: 'id-ID', region: 'Indonesia' }] },
+  { name: 'Bahasa Melayu', iso: 'ms', englishName: 'malay', dialects: [{ code: 'ms-MY', region: 'Malaysia' }] },
+  { name: 'Català', iso: 'ca', englishName: 'catalan', dialects: [{ code: 'ca-ES', region: 'Spain' }] },
+  { name: 'Čeština', iso: 'cs', englishName: 'czech', dialects: [{ code: 'cs-CZ', region: 'Czechia' }] },
+  { name: 'Dansk', iso: 'da', englishName: 'danish', dialects: [{ code: 'da-DK', region: 'Denmark' }] },
+  { name: 'Deutsch', iso: 'de', englishName: 'german', dialects: [{ code: 'de-DE', region: 'Germany' }] },
+  {
+    name: 'English', iso: 'en', englishName: 'english',
+    dialects: [
+      { code: 'en-US', region: 'United States' },
+      { code: 'en-GB', region: 'United Kingdom' },
+      { code: 'en-AU', region: 'Australia' },
+      { code: 'en-CA', region: 'Canada' },
+      { code: 'en-IN', region: 'India' },
+      { code: 'en-NZ', region: 'New Zealand' },
+      { code: 'en-PH', region: 'Philippines' },
+      { code: 'en-ZA', region: 'South Africa' },
+      { code: 'en-NG', region: 'Nigeria' },
+      { code: 'en-GH', region: 'Ghana' },
+      { code: 'en-KE', region: 'Kenya' },
+      { code: 'en-TZ', region: 'Tanzania' },
+    ],
+  },
+  {
+    name: 'Español', iso: 'es', englishName: 'spanish',
+    dialects: [
+      { code: 'es-ES', region: 'España' },
+      { code: 'es-MX', region: 'México' },
+      { code: 'es-US', region: 'Estados Unidos' },
+      { code: 'es-AR', region: 'Argentina' },
+      { code: 'es-CL', region: 'Chile' },
+      { code: 'es-CO', region: 'Colombia' },
+      { code: 'es-PE', region: 'Perú' },
+      { code: 'es-VE', region: 'Venezuela' },
+      { code: 'es-EC', region: 'Ecuador' },
+      { code: 'es-GT', region: 'Guatemala' },
+      { code: 'es-CR', region: 'Costa Rica' },
+      { code: 'es-PA', region: 'Panamá' },
+      { code: 'es-DO', region: 'Rep. Dominicana' },
+      { code: 'es-UY', region: 'Uruguay' },
+      { code: 'es-PY', region: 'Paraguay' },
+      { code: 'es-BO', region: 'Bolivia' },
+      { code: 'es-SV', region: 'El Salvador' },
+      { code: 'es-HN', region: 'Honduras' },
+      { code: 'es-NI', region: 'Nicaragua' },
+      { code: 'es-PR', region: 'Puerto Rico' },
+    ],
+  },
+  { name: 'Euskara', iso: 'eu', englishName: 'basque', dialects: [{ code: 'eu-ES', region: 'Spain' }] },
+  { name: 'Filipino', iso: 'fil', englishName: 'filipino tagalog', dialects: [{ code: 'fil-PH', region: 'Philippines' }] },
+  { name: 'Français', iso: 'fr', englishName: 'french', dialects: [{ code: 'fr-FR', region: 'France' }] },
+  { name: 'Basa Jawa', iso: 'jv', englishName: 'javanese', dialects: [{ code: 'jv-ID', region: 'Indonesia' }] },
+  { name: 'Galego', iso: 'gl', englishName: 'galician', dialects: [{ code: 'gl-ES', region: 'Spain' }] },
+  { name: 'ગુજરાતી', iso: 'gu', englishName: 'gujarati', dialects: [{ code: 'gu-IN', region: 'India' }] },
+  { name: 'Hrvatski', iso: 'hr', englishName: 'croatian', dialects: [{ code: 'hr-HR', region: 'Croatia' }] },
+  { name: 'IsiZulu', iso: 'zu', englishName: 'zulu', dialects: [{ code: 'zu-ZA', region: 'South Africa' }] },
+  { name: 'Íslenska', iso: 'is', englishName: 'icelandic', dialects: [{ code: 'is-IS', region: 'Iceland' }] },
+  {
+    name: 'Italiano', iso: 'it', englishName: 'italian',
+    dialects: [
+      { code: 'it-IT', region: 'Italia' },
+      { code: 'it-CH', region: 'Svizzera' },
+    ],
+  },
+  { name: 'ಕನ್ನಡ', iso: 'kn', englishName: 'kannada', dialects: [{ code: 'kn-IN', region: 'India' }] },
+  { name: 'ភាសាខ្មែរ', iso: 'km', englishName: 'khmer cambodian', dialects: [{ code: 'km-KH', region: 'Cambodia' }] },
+  { name: 'Latviešu', iso: 'lv', englishName: 'latvian', dialects: [{ code: 'lv-LV', region: 'Latvia' }] },
+  { name: 'Lietuvių', iso: 'lt', englishName: 'lithuanian', dialects: [{ code: 'lt-LT', region: 'Lithuania' }] },
+  { name: 'മലയാളം', iso: 'ml', englishName: 'malayalam', dialects: [{ code: 'ml-IN', region: 'India' }] },
+  { name: 'मराठी', iso: 'mr', englishName: 'marathi', dialects: [{ code: 'mr-IN', region: 'India' }] },
+  { name: 'Magyar', iso: 'hu', englishName: 'hungarian', dialects: [{ code: 'hu-HU', region: 'Hungary' }] },
+  { name: 'ລາວ', iso: 'lo', englishName: 'lao laotian', dialects: [{ code: 'lo-LA', region: 'Laos' }] },
+  { name: 'Nederlands', iso: 'nl', englishName: 'dutch', dialects: [{ code: 'nl-NL', region: 'Netherlands' }] },
+  { name: 'नेपाली भाषा', iso: 'ne', englishName: 'nepali', dialects: [{ code: 'ne-NP', region: 'Nepal' }] },
+  { name: 'Norsk bokmål', iso: 'nb', englishName: 'norwegian bokmal', dialects: [{ code: 'nb-NO', region: 'Norway' }] },
+  { name: 'Polski', iso: 'pl', englishName: 'polish', dialects: [{ code: 'pl-PL', region: 'Poland' }] },
+  {
+    name: 'Português', iso: 'pt', englishName: 'portuguese',
+    dialects: [
+      { code: 'pt-BR', region: 'Brasil' },
+      { code: 'pt-PT', region: 'Portugal' },
+    ],
+  },
+  { name: 'Română', iso: 'ro', englishName: 'romanian', dialects: [{ code: 'ro-RO', region: 'Romania' }] },
+  { name: 'සිංහල', iso: 'si', englishName: 'sinhala sinhalese', dialects: [{ code: 'si-LK', region: 'Sri Lanka' }] },
+  { name: 'Slovenščina', iso: 'sl', englishName: 'slovenian', dialects: [{ code: 'sl-SI', region: 'Slovenia' }] },
+  { name: 'Basa Sunda', iso: 'su', englishName: 'sundanese', dialects: [{ code: 'su-ID', region: 'Indonesia' }] },
+  { name: 'Slovenčina', iso: 'sk', englishName: 'slovak', dialects: [{ code: 'sk-SK', region: 'Slovakia' }] },
+  { name: 'Suomi', iso: 'fi', englishName: 'finnish', dialects: [{ code: 'fi-FI', region: 'Finland' }] },
+  { name: 'Svenska', iso: 'sv', englishName: 'swedish', dialects: [{ code: 'sv-SE', region: 'Sweden' }] },
+  {
+    name: 'Kiswahili', iso: 'sw', englishName: 'swahili',
+    dialects: [
+      { code: 'sw-TZ', region: 'Tanzania' },
+      { code: 'sw-KE', region: 'Kenya' },
+    ],
+  },
+  { name: 'ქართული', iso: 'ka', englishName: 'georgian', dialects: [{ code: 'ka-GE', region: 'Georgia' }] },
+  { name: 'Հայերեն', iso: 'hy', englishName: 'armenian', dialects: [{ code: 'hy-AM', region: 'Armenia' }] },
+  {
+    name: 'தமிழ்', iso: 'ta', englishName: 'tamil',
+    dialects: [
+      { code: 'ta-IN', region: 'இந்தியா' },
+      { code: 'ta-SG', region: 'சிங்கப்பூர்' },
+      { code: 'ta-LK', region: 'இலங்கை' },
+      { code: 'ta-MY', region: 'மலேசியா' },
+    ],
+  },
+  { name: 'తెలుగు', iso: 'te', englishName: 'telugu', dialects: [{ code: 'te-IN', region: 'India' }] },
+  { name: 'Tiếng Việt', iso: 'vi', englishName: 'vietnamese', dialects: [{ code: 'vi-VN', region: 'Vietnam' }] },
+  { name: 'Türkçe', iso: 'tr', englishName: 'turkish', dialects: [{ code: 'tr-TR', region: 'Türkiye' }] },
+  {
+    name: 'اُردُو', iso: 'ur', englishName: 'urdu',
+    dialects: [
+      { code: 'ur-PK', region: 'پاکستان' },
+      { code: 'ur-IN', region: 'بھارت' },
+    ],
+  },
+  { name: 'Ελληνικά', iso: 'el', englishName: 'greek', dialects: [{ code: 'el-GR', region: 'Greece' }] },
+  { name: 'български', iso: 'bg', englishName: 'bulgarian', dialects: [{ code: 'bg-BG', region: 'Bulgaria' }] },
+  { name: 'Русский', iso: 'ru', englishName: 'russian', dialects: [{ code: 'ru-RU', region: 'Russia' }] },
+  { name: 'Српски', iso: 'sr', englishName: 'serbian', dialects: [{ code: 'sr-RS', region: 'Serbia' }] },
+  { name: 'Українська', iso: 'uk', englishName: 'ukrainian', dialects: [{ code: 'uk-UA', region: 'Ukraine' }] },
+  { name: '한국어', iso: 'ko', englishName: 'korean', dialects: [{ code: 'ko-KR', region: 'Korea' }] },
+  {
+    name: '中文', iso: 'cmn', englishName: 'chinese mandarin cantonese',
+    dialects: [
+      { code: 'cmn-Hans-CN', region: '普通话 (中国大陆)' },
+      { code: 'cmn-Hans-HK', region: '普通话 (香港)' },
+      { code: 'cmn-Hant-TW', region: '中文 (台灣)' },
+      { code: 'yue-Hant-HK', region: '粵語 (香港)' },
+    ],
+  },
+  { name: '日本語', iso: 'ja', englishName: 'japanese', dialects: [{ code: 'ja-JP', region: 'Japan' }] },
+  { name: 'हिन्दी', iso: 'hi', englishName: 'hindi', dialects: [{ code: 'hi-IN', region: 'India' }] },
+  { name: 'ภาษาไทย', iso: 'th', englishName: 'thai', dialects: [{ code: 'th-TH', region: 'Thailand' }] },
+];
+
+/** Flat list of every supported BCP-47 tag, useful for validation. */
+export const WEB_SPEECH_TAGS: string[] = WEB_SPEECH_LANGUAGES.flatMap((l) =>
+  l.dialects.map((d) => d.code),
+);
+
+/**
+ * Find the human-readable language entry that owns a given BCP-47 tag.
+ * Returns `null` for unknown / custom tags (custom engines may use
+ * codes outside this catalogue).
+ */
+export function findSpeechLanguage(tag: string | null | undefined): {
+  language: SpeechLanguage;
+  dialect: SpeechLanguageDialect;
+} | null {
+  if (!tag) return null;
+  const lower = tag.toLowerCase();
+  for (const language of WEB_SPEECH_LANGUAGES) {
+    for (const dialect of language.dialects) {
+      if (dialect.code.toLowerCase() === lower) return { language, dialect };
+    }
+  }
+  return null;
+}
+
+/**
+ * Extract the ISO-3166 country code (2 uppercase letters) from a
+ * BCP-47 tag, or `null` if the tag has no region subtag. Used by the
+ * language flag button to find the right country flag asset.
+ */
+export function countryFromTag(tag: string | null | undefined): string | null {
+  if (!tag) return null;
+  const parts = tag.split('-');
+  for (let i = parts.length - 1; i >= 0; i -= 1) {
+    const p = parts[i];
+    if (p.length === 2 && /^[A-Za-z]{2}$/.test(p)) return p.toUpperCase();
+  }
+  return null;
+}

package/src/tools/SpeechRecognition/core/logger.ts

@@ -0,0 +1,3 @@
+import { consola } from 'consola';
+
+export const sttLogger = consola.withTag('ui-tools:speech');

package/src/tools/SpeechRecognition/core/reducer.ts

@@ -0,0 +1,105 @@
+import { newSegmentId } from './ids';
+import type {
+  RecognitionError,
+  RecognitionStatus,
+  Segment,
+} from '../types';
+
+export interface RecognitionState {
+  status: RecognitionStatus;
+  segments: Segment[];
+  error: RecognitionError | null;
+  startedAt: number | null;
+}
+
+export const INITIAL_STATE: RecognitionState = {
+  status: 'idle',
+  segments: [],
+  error: null,
+  startedAt: null,
+};
+
+export type RecognitionAction =
+  | { type: 'START' }
+  | { type: 'STARTED' }
+  | { type: 'STOP' }
+  | { type: 'STOPPED' }
+  | { type: 'ABORT' }
+  | {
+      type: 'PARTIAL';
+      text: string;
+      segmentId: string;
+      confidence?: number;
+    }
+  | {
+      type: 'FINAL';
+      text: string;
+      segmentId: string;
+      confidence?: number;
+    }
+  | { type: 'ERROR'; error: RecognitionError }
+  | { type: 'RESET' };
+
+function nowSinceStart(state: RecognitionState): number {
+  return state.startedAt ? Date.now() - state.startedAt : 0;
+}
+
+function upsertSegment(
+  segments: Segment[],
+  patch: Segment,
+): Segment[] {
+  const idx = segments.findIndex((s) => s.id === patch.id);
+  if (idx === -1) return [...segments, patch];
+  const next = segments.slice();
+  next[idx] = { ...next[idx], ...patch };
+  return next;
+}
+
+export function reducer(
+  state: RecognitionState,
+  action: RecognitionAction,
+): RecognitionState {
+  switch (action.type) {
+    case 'START':
+      return {
+        ...state,
+        status: 'starting',
+        error: null,
+        startedAt: Date.now(),
+      };
+    case 'STARTED':
+      return { ...state, status: 'listening' };
+    case 'STOP':
+      return { ...state, status: 'stopping' };
+    case 'STOPPED':
+    case 'ABORT':
+      return { ...state, status: 'idle' };
+    case 'PARTIAL': {
+      const seg: Segment = {
+        id: action.segmentId,
+        text: action.text,
+        isFinal: false,
+        confidence: action.confidence,
+        startedAt: nowSinceStart(state),
+      };
+      return { ...state, segments: upsertSegment(state.segments, seg) };
+    }
+    case 'FINAL': {
+      const seg: Segment = {
+        id: action.segmentId || newSegmentId(),
+        text: action.text,
+        isFinal: true,
+        confidence: action.confidence,
+        startedAt: nowSinceStart(state),
+        endedAt: nowSinceStart(state),
+      };
+      return { ...state, segments: upsertSegment(state.segments, seg) };
+    }
+    case 'ERROR':
+      return { ...state, status: 'error', error: action.error };
+    case 'RESET':
+      return { ...INITIAL_STATE };
+    default:
+      return state;
+  }
+}

package/src/tools/SpeechRecognition/core/transcript.ts

@@ -0,0 +1,36 @@
+import type { Segment, Transcript } from '../types';
+
+export const EMPTY_TRANSCRIPT: Transcript = {
+  interim: '',
+  final: '',
+  segments: [],
+};
+
+export function joinFinal(segments: Segment[]): string {
+  let out = '';
+  for (const seg of segments) {
+    if (!seg.isFinal) continue;
+    const text = seg.text.trim();
+    if (!text) continue;
+    out = out ? `${out} ${text}` : text;
+  }
+  return out;
+}
+
+export function buildTranscript(segments: Segment[]): Transcript {
+  const last = segments[segments.length - 1];
+  const interim = last && !last.isFinal ? last.text : '';
+  return {
+    interim,
+    final: joinFinal(segments),
+    segments,
+  };
+}
+
+/**
+ * Polite text normalisation between concatenated finals — strips double
+ * spaces / leading punctuation that some engines emit when the user pauses.
+ */
+export function normaliseFinal(text: string): string {
+  return text.replace(/\s+/g, ' ').replace(/\s+([,.!?])/g, '$1').trim();
+}

package/src/tools/SpeechRecognition/hooks/index.ts

@@ -0,0 +1,14 @@
+export { useSpeechRecognition } from './useSpeechRecognition';
+export { useDictation } from './useDictation';
+export type { UseDictationConfig, UseDictationReturn } from './useDictation';
+export { useMicDevices } from './useMicDevices';
+export type { MicDevice } from './useMicDevices';
+export { useMicLevel } from './useMicLevel';
+export { usePushToTalk } from './usePushToTalk';
+export type { UsePushToTalkOptions } from './usePushToTalk';
+export { useEnginePrefs } from './useEnginePrefs';
+export { useVoiceSupport } from './useVoiceSupport';
+export type { VoiceSupport, VoiceUnsupportedReason } from './useVoiceSupport';
+export { useResolvedLanguage } from './useResolvedLanguage';
+export { useSpeechLanguageInfo } from './useSpeechLanguageInfo';
+export type { SpeechLanguageInfo } from './useSpeechLanguageInfo';

package/src/tools/SpeechRecognition/hooks/useDictation.ts

@@ -0,0 +1,59 @@
+'use client';
+
+import { useEffect, useRef } from 'react';
+
+import { normaliseFinal } from '../core/transcript';
+import type { UseSpeechRecognitionConfig, UseSpeechRecognitionReturn } from '../types';
+import { useSpeechRecognition } from './useSpeechRecognition';
+
+export interface UseDictationConfig
+  extends Omit<UseSpeechRecognitionConfig, 'onFinal'> {
+  /** Controlled value the dictation is appending to. */
+  value: string;
+  /** Called with the next value after each final segment lands. */
+  onChange: (next: string) => void;
+  /** Joiner between the previous value and the new segment. Default ' '. */
+  separator?: string;
+}
+
+export interface UseDictationReturn extends UseSpeechRecognitionReturn {
+  /** Convenience — same as `toggle`, named for dictation UIs. */
+  toggleDictation: () => Promise<void>;
+}
+
+/**
+ * Convenience adapter that pipes final transcript segments straight into
+ * a controlled string (`<textarea>` / `<input>` / TipTap). Interim text
+ * is left alone — bind `transcript.interim` separately if you want to
+ * show a live ghost.
+ */
+export function useDictation(config: UseDictationConfig): UseDictationReturn {
+  const { value, onChange, separator = ' ', ...rest } = config;
+
+  // Stash latest value in a ref so the onFinal closure always sees the
+  // freshest text without forcing the underlying hook to resubscribe.
+  const valueRef = useRef(value);
+  valueRef.current = value;
+  const onChangeRef = useRef(onChange);
+  onChangeRef.current = onChange;
+
+  const rec = useSpeechRecognition({
+    ...rest,
+    onFinal: (text) => {
+      const clean = normaliseFinal(text);
+      if (!clean) return;
+      const prev = valueRef.current;
+      const next = prev ? `${prev}${separator}${clean}` : clean;
+      onChangeRef.current(next);
+    },
+  });
+
+  useEffect(() => {
+    valueRef.current = value;
+  }, [value]);
+
+  return {
+    ...rec,
+    toggleDictation: rec.toggle,
+  };
+}

package/src/tools/SpeechRecognition/hooks/useEnginePrefs.ts

@@ -0,0 +1,15 @@
+'use client';
+
+import { useSpeechPrefs } from '../store/prefsStore';
+import type { SpeechPrefs } from '../store/prefsStore';
+
+/** Thin selector hook so consumers can subscribe to prefs without pulling the whole zustand store. */
+export function useEnginePrefs(): SpeechPrefs & {
+  setLanguage: (v: string) => void;
+  setDeviceId: (v: string | null) => void;
+  setEngineId: (v: string | null) => void;
+  setEarcons: (v: boolean) => void;
+  reset: () => void;
+} {
+  return useSpeechPrefs();
+}

package/src/tools/SpeechRecognition/hooks/useMicDevices.ts

@@ -0,0 +1,57 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+
+import { sttLogger } from '../core/logger';
+
+export interface MicDevice {
+  deviceId: string;
+  label: string;
+  groupId: string;
+}
+
+/**
+ * Enumerates `audioinput` devices. The browser hides labels until the
+ * page has been granted mic permission at least once — the consumer
+ * should call `useSpeechRecognition().start()` first to populate labels.
+ */
+export function useMicDevices(): {
+  devices: MicDevice[];
+  refresh: () => Promise<void>;
+} {
+  const [devices, setDevices] = useState<MicDevice[]>([]);
+
+  async function refresh(): Promise<void> {
+    if (typeof navigator === 'undefined' || !navigator.mediaDevices?.enumerateDevices) {
+      return;
+    }
+    try {
+      const list = await navigator.mediaDevices.enumerateDevices();
+      setDevices(
+        list
+          .filter((d) => d.kind === 'audioinput')
+          .map((d) => ({
+            deviceId: d.deviceId,
+            label: d.label || 'Microphone',
+            groupId: d.groupId,
+          })),
+      );
+    } catch (cause) {
+      sttLogger.warn('[devices] enumerate failed', cause);
+    }
+  }
+
+  useEffect(() => {
+    void refresh();
+    if (typeof navigator === 'undefined' || !navigator.mediaDevices) return undefined;
+    const handler = (): void => {
+      void refresh();
+    };
+    navigator.mediaDevices.addEventListener?.('devicechange', handler);
+    return () => {
+      navigator.mediaDevices.removeEventListener?.('devicechange', handler);
+    };
+  }, []);
+
+  return { devices, refresh };
+}