@djangocfg/widget-chat 0.1.1

package/src/core/voice/earcons.ts

@@ -0,0 +1,58 @@
+/**
+ * The two dictation earcons, as a port.
+ *
+ * The session plays them, not the button: the button knows what was pressed,
+ * only the session knows what the engine did. A permission prompt, a silence
+ * timeout and an already-running engine all sit between the two.
+ *
+ * ORDER: the start tone plays before the engine is asked to listen, the stop
+ * tone after it is told to stop. A tone inside that window is transcribed as a
+ * word. Reversing either line is silent — dictation still works and the
+ * transcript merely gains a phantom syllable.
+ */
+
+export type EarconKind = "start" | "stop";
+
+/**
+ * How a host plays one tone.
+ *
+ * A function, not a URL pair: the package ships no audio. The host already owns
+ * preloading, the mute gate and the autoplay-rejection rule.
+ *
+ * Must not throw and must not block — it runs on the path that opens the
+ * microphone.
+ */
+export type PlayEarcon = (kind: EarconKind) => void;
+
+/**
+ * The dictation-tones capability.
+ *
+ * Separate from `VoiceCapability` because an absent voice capability means the
+ * DEFAULT engine — a host on that path has no object to hang a player on. Sound
+ * and engine are also independent choices: the browser's recogniser with our
+ * tones, or the reverse.
+ *
+ * Declared here rather than in `core/capabilities.ts` so the port, the safety
+ * wrapper and the seam that exposes them stay in one file.
+ */
+export interface VoiceSoundsCapability {
+  readonly play: PlayEarcon;
+}
+
+/**
+ * Wrap a player so a throwing host costs a tone, not the sentence.
+ *
+ * `undefined` in ⇒ no-op out, so the session holds one shape and needs no null
+ * check at either call site.
+ */
+export function safeEarcon(play: PlayEarcon | undefined): PlayEarcon {
+  if (play === undefined) return () => undefined;
+  return (kind) => {
+    try {
+      play(kind);
+    } catch {
+      // Silent: this would fire once per dictation and train the reader to
+      // ignore the screen during voice work.
+    }
+  };
+}

package/src/core/voice/index.ts

@@ -0,0 +1,26 @@
+// Dictation: a state machine, a language rule, and ONE default engine.
+//
+// The package ships Web Speech as a default so a consumer gets a working
+// microphone without wiring an external toolkit — audio never leaves the
+// engine there. `VoiceCapability` remains the seam, so a host with a server
+// transcriber, Whisper or a native bridge supplies its own and the default
+// steps aside. Neither available means NO button, never a disabled one.
+//
+// This inverts the absent-is-absent rule for this one capability, deliberately:
+// absent `voice` falls back to the browser rather than to nothing.
+//
+// MediaRecorder is NOT a fallback. It only produces audio, and turning that
+// into text needs an endpoint — audio leaving the device, which is exactly the
+// decision the seam exists to leave to the host.
+
+export { WEB_SPEECH_LANGUAGES } from "./languages";
+export type { SpeechLanguage, SpeechLanguageDialect } from "./languages";
+export { expandQueryLayouts, matchesLanguageQuery } from "./language-search";
+export { resolveLanguage, toSpeechTag } from "./resolve-language";
+export type { LanguageSignals } from "./resolve-language";
+export { createWebSpeechCapability, isWebSpeechAvailable } from "./web-speech";
+export type { WebSpeechOptions } from "./web-speech";
+export { VoiceSession } from "./session";
+export type { VoiceSnapshot, VoiceSessionOptions } from "./session";
+export { safeEarcon } from "./earcons";
+export type { EarconKind, PlayEarcon, VoiceSoundsCapability } from "./earcons";

package/src/core/voice/language-search.ts

@@ -0,0 +1,62 @@
+/**
+ * Layout-independent language search.
+ *
+ * Typing "he,bq" on an EN layout while thinking «русый», or "hecc" for
+ * «русс», is the single most common way a bilingual user searches a
+ * language list — the physical keys are right, the layout is wrong.
+ * Every query is therefore expanded through the QWERTY↔ЙЦУКЕН key maps
+ * and EVERY variant is matched, so «рус», "rus", "russian" and "hec"
+ * (=рус on EN keys) all find Русский.
+ *
+ * The maps cover the RU↔EN pair only — the pair our users actually mix.
+ * The mechanism is additive: more layout pairs can be appended to
+ * `LAYOUT_PAIRS` without touching the matcher.
+ */
+
+/** QWERTY key → ЙЦУКЕН character on the same physical key. */
+const EN_TO_RU: Record<string, string> = {
+  q: 'й', w: 'ц', e: 'у', r: 'к', t: 'е', y: 'н', u: 'г', i: 'ш', o: 'щ',
+  p: 'з', '[': 'х', ']': 'ъ', a: 'ф', s: 'ы', d: 'в', f: 'а', g: 'п',
+  h: 'р', j: 'о', k: 'л', l: 'д', ';': 'ж', "'": 'э', z: 'я', x: 'ч',
+  c: 'с', v: 'м', b: 'и', n: 'т', m: 'ь', ',': 'б', '.': 'ю',
+};
+
+/** ЙЦУКЕН character → QWERTY key on the same physical key. */
+const RU_TO_EN: Record<string, string> = Object.fromEntries(
+  Object.entries(EN_TO_RU).map(([en, ru]) => [ru, en]),
+);
+
+const LAYOUT_PAIRS: Record<string, string>[] = [EN_TO_RU, RU_TO_EN];
+
+function remap(query: string, table: Record<string, string>): string {
+  let out = '';
+  for (const ch of query) out += table[ch] ?? ch;
+  return out;
+}
+
+/**
+ * All layout interpretations of a raw query, lowercased and de-duplicated.
+ * Always includes the query itself.
+ */
+export function expandQueryLayouts(query: string): string[] {
+  const q = query.trim().toLowerCase();
+  if (!q) return [];
+  const variants = new Set<string>([q]);
+  for (const table of LAYOUT_PAIRS) {
+    const mapped = remap(q, table);
+    if (mapped !== q) variants.add(mapped);
+  }
+  return [...variants];
+}
+
+/**
+ * True when ANY layout variant of `query` is a substring of `haystack`.
+ * `haystack` must already be lowercase (build it once per row —
+ * `SpeechLanguageRow.search` packs native name, English name, ISO, tag
+ * and region).
+ */
+export function matchesLanguageQuery(haystack: string, query: string): boolean {
+  const variants = expandQueryLayouts(query);
+  if (variants.length === 0) return true;
+  return variants.some((v) => haystack.includes(v));
+}

package/src/core/voice/languages.ts

@@ -0,0 +1,267 @@
+/**
+ * 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.
+ *
+ * A host whose engine is not the browser can narrow this list — a server
+ * transcriber may accept more or fewer tags than Web Speech does.
+ */
+
+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`). The key a UI locale
+   * is matched against when resolving a default.
+   */
+  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 && p.length === 2 && /^[A-Za-z]{2}$/.test(p)) return p.toUpperCase();
+  }
+  return null;
+}
+
+export interface SpeechLanguageRow {
+  /** BCP-47 tag (e.g. `ru-RU`). */
+  tag: string;
+  /** Display label: native name, plus region when the language has >1 dialect. */
+  label: string;
+  /** ISO-3166 country for the flag asset, or null for region-less tags. */
+  country: string | null;
+  /**
+   * Lowercased search haystack: native name + English name + ISO + tag
+   * + region. Match with `matchesLanguageQuery` (layout-independent).
+   */
+  search: string;
+}
+
+/**
+ * Flatten the catalogue into ready-to-render menu rows — the single
+ * builder behind every language list surface (`VoiceControlMenu`
+ * submenu, the in-recording `LanguageChip` dropdown). `allowedTags`
+ * narrows the list for backend engines that support a subset.
+ */
+export function buildLanguageRows(allowedTags?: string[]): SpeechLanguageRow[] {
+  const allow = allowedTags ? new Set(allowedTags) : null;
+  const rows: SpeechLanguageRow[] = [];
+  for (const lang of WEB_SPEECH_LANGUAGES) {
+    for (const d of lang.dialects) {
+      if (allow && !allow.has(d.code)) continue;
+      rows.push({
+        tag: d.code,
+        label:
+          lang.dialects.length === 1 ? lang.name : `${lang.name} — ${d.region}`,
+        country: countryFromTag(d.code),
+        search:
+          `${lang.name} ${lang.englishName} ${lang.iso} ${d.code} ${d.region}`.toLowerCase(),
+      });
+    }
+  }
+  return rows;
+}

package/src/core/voice/resolve-language.ts

@@ -0,0 +1,93 @@
+import { WEB_SPEECH_LANGUAGES } from "./languages";
+
+/**
+ * The signals a default language is resolved from.
+ *
+ * Passed in rather than read from `navigator`/`localStorage` here: this is the
+ * one rule in dictation worth testing exhaustively, and a function that reaches
+ * for globals can only be tested by faking them.
+ */
+export interface LanguageSignals {
+  /** What the user picked, if they ever did. Wins outright. */
+  readonly picked?: string | undefined;
+  /** The host UI's locale — an ISO subtag such as `ru`. A TIE-BREAKER only. */
+  readonly uiLocale?: string | undefined;
+  /** `navigator.languages`, in the browser's own order. */
+  readonly browserLanguages?: readonly string[] | undefined;
+  /** `navigator.language`. */
+  readonly browserLanguage?: string | undefined;
+}
+
+const FALLBACK = "en-US";
+
+/** ISO primary subtag → the catalogue's default dialect (`uk` → `uk-UA`). */
+const ISO_TO_TAG: ReadonlyMap<string, string> = new Map(
+  WEB_SPEECH_LANGUAGES.flatMap((language) => {
+    const first = language.dialects[0];
+    return first === undefined ? [] : [[language.iso.toLowerCase(), first.code] as const];
+  }),
+);
+
+/** Every tag the catalogue knows, lowercased, for validating a candidate. */
+const KNOWN_TAGS: ReadonlySet<string> = new Set(
+  WEB_SPEECH_LANGUAGES.flatMap((language) =>
+    language.dialects.map((dialect) => dialect.code.toLowerCase()),
+  ),
+);
+
+function isoOf(tag: string): string {
+  return tag.toLowerCase().split("-")[0] ?? "";
+}
+
+/**
+ * Normalise anything language-shaped to a tag the Web Speech API accepts.
+ *
+ * A bare ISO subtag becomes the catalogue's default dialect for it; a full tag
+ * is kept when the catalogue knows it, and otherwise falls back to that
+ * language's default dialect. The last step is what rescues the measured case:
+ * `en-ID` is a real browser value and not a speech tag, so it resolves to
+ * `en-US` rather than being handed to an engine that will reject it.
+ */
+export function toSpeechTag(code: string | null | undefined): string | undefined {
+  if (code === null || code === undefined) return undefined;
+  const trimmed = code.trim();
+  if (trimmed === "") return undefined;
+  if (KNOWN_TAGS.has(trimmed.toLowerCase())) return trimmed;
+  return ISO_TO_TAG.get(isoOf(trimmed));
+}
+
+/**
+ * Which language dictation should listen for.
+ *
+ * The order is load-bearing, and rung 2 is the one that is easy to get wrong in
+ * both directions:
+ *
+ *   1. the user's explicit pick
+ *   2. the UI locale, IF the browser also lists it as spoken
+ *   3. `navigator.language`
+ *   4. `en-US`
+ *
+ * Rung 2 exists because of a measured failure: `navigator.language` was `en-ID`
+ * while `navigator.languages` contained `ru` and the app was set to Russian.
+ * Reading position one alone threw away two independent signals and left
+ * dictation deaf to the language the user was actually speaking.
+ *
+ * It is deliberately NOT "use the UI locale". Pinning speech to the app locale
+ * is a known regression — an English UI then cannot dictate Russian. The UI
+ * locale is only allowed to break a tie the BROWSER has already declared
+ * plausible, so an English app on a browser listing no Russian still gets
+ * English.
+ */
+export function resolveLanguage(signals: LanguageSignals): string {
+  const picked = toSpeechTag(signals.picked);
+  if (picked !== undefined) return picked;
+
+  const spoken = (signals.browserLanguages ?? []).map(isoOf);
+  const uiIso = isoOf(signals.uiLocale ?? "");
+  if (uiIso !== "" && spoken.includes(uiIso)) {
+    const tag = ISO_TO_TAG.get(uiIso);
+    if (tag !== undefined) return tag;
+  }
+
+  return toSpeechTag(signals.browserLanguage) ?? FALLBACK;
+}