@alia.onl/sdk 7.2.9 → 10.0.0

package/src/index.ts

@@ -13,7 +13,7 @@ export { IdentityMark } from './components/IdentityMark';
 export type { IdentityMarkProps, IdentityMarkState } from './components/IdentityMark';
 export { ThinkingIndicator } from './components/ThinkingIndicator';
 export { AliaMarkdown } from './components/Markdown';
-export type { AliaMarkdownProps } from './components/Markdown';
+export type { AliaMarkdownProps, RenderCodeBlock } from './components/Markdown';
 export { Reasoning, ReasoningTrigger, ReasoningContent } from './components/Reasoning';
 export { AliaWelcomeMessage } from './components/AliaWelcomeMessage';
 export { ResearchProgressCard } from './components/ResearchProgressCard';
@@ -27,11 +27,13 @@ export type { UseAliaChatOptions, UseAliaChatReturn } from './hooks/useAliaChat'
 export { useTTS } from './hooks/useTTS';
 export type { UseTTSOptions } from './hooks/useTTS';
 export { useSpeechToText, useSTTStore } from './hooks/useSpeechToText';
+export { VOICE_ERROR_MESSAGES } from './lib/speech-messages';
+export type { VoiceErrorCode } from './lib/speech-messages';
 export type { UseSTTOptions } from './hooks/useSpeechToText';
 
 // ── Model catalogue (GET /catalogue) ──
-// Exported so a consumer building its own picker reads the surface the SDK
-// reads, rather than hardcoding an identifier the way this package used to.
+// Exported so a consumer building its own picker reads the real models the
+// server offers; the SDK itself ships no model identifier.
 export {
   fetchCatalogue,
   parseCatalogue,
@@ -39,8 +41,7 @@ export {
   resolveModelId,
   clearCatalogueCache,
 } from './lib/catalogue';
-export type { CatalogueEntry, CatalogueEntryKind, ModelSelection } from './lib/catalogue';
-export { PREFERRED_CHAT_MODEL_ID, PREFERRED_VOICE_MODEL_ID } from './lib/config';
+export type { Catalogue, CatalogueEntry, ModelSelection, ReasoningEffort } from './lib/catalogue';
 
 // ── Types ──
 export type {
@@ -64,24 +65,10 @@ export type {
 export { Button, buttonVariants, buttonTextVariants } from './components/ui/button';
 export type { ButtonProps } from './components/ui/button';
 export { Text, TextClassContext } from './components/ui/text';
-export { ChatTextInput } from './components/ui/chat-text-input';
 export { cn, formatFileSize } from './lib/utils';
 export { getToolLabel, getToolActiveLabel, getResearchActiveLabel } from './lib/tool-registry';
 export { getTextFromContent, getImagesFromContent } from './lib/content-utils';
 
-// ── PromptInput ──
-export { PromptInput } from './components/ui/prompt-input/prompt-input';
-export type { PromptInputProps } from './components/ui/prompt-input/prompt-input';
-export { usePromptInput, useIsFullscreen, PromptInputContext } from './components/ui/prompt-input/context';
-export type { Attachment, Completion, PromptInputContextType } from './components/ui/prompt-input/context';
-export { PromptInputTextarea } from './components/ui/prompt-input/textarea';
-export { PromptInputActions } from './components/ui/prompt-input/actions';
-export { PromptInputSubmitButton } from './components/ui/prompt-input/submit-button';
-export { PromptInputMicButton } from './components/ui/prompt-input/mic-button';
-export { PromptInputAddMenu } from './components/ui/prompt-input/add-menu';
-export { PromptInputAttachments } from './components/ui/prompt-input/attachments';
-export { PromptInputAutocomplete } from './components/ui/prompt-input/autocomplete';
-
 // ── Picker hooks ──
 export { useImagePicker } from './hooks/useImagePicker';
 export type { ImagePickerAsset } from './hooks/useImagePicker';

package/src/lib/audio-level.ts

@@ -2,8 +2,9 @@
  * How audio becomes the ambient field's 0..1 level — one curve, one pair of
  * time constants, for every source that drives it.
  *
- * Dictation got here first and is the reference: the recorder reports dBFS,
- * `useSpeechToText` normalises it against a -60 floor, and `useAmbientWave`
+ * Dictation got here first and is the reference: the microphone's level is
+ * taken as dBFS (on web, from an analyser beside the recognizer —
+ * `speech-recognition.ts`), normalised against a -60 floor, and `useAmbientWave`
  * smooths it with a fast attack and a slow decay before it reaches
  * `AmbientField`. That is the behaviour people like, so it is the behaviour
  * everything else adopts rather than re-invents — including "read aloud", which

package/src/lib/catalogue.ts

@@ -1,58 +1,56 @@
 /**
- * The model catalogue, as the SDK consumes it (`GET /catalogue`, epic #139
- * workstream 5).
+ * The model catalogue, as the SDK consumes it (`GET /catalogue`).
  *
- * Every surface used to hardcode an `alia-*` identifier as its default —
- * `useAliaChat` sent `route:auto`, `useTTS` and `useVoiceRoom` sent `route:voice`
- * — which meant a retired identifier became a 400 in a consumer's app with
- * nothing the consumer could do about it, since the string was baked into the
- * package they installed. This module is how the SDK asks the server what it
- * offers instead.
+ * Alia has no models of its own: the catalogue lists the real models Oxy serves
+ * (ids `publisher/model`), and the server decides which one a request with no
+ * `model` gets (`defaultModelId`) and which ones a picker shows first
+ * (`featuredIds`). This package therefore ships NO model identifier: a caller
+ * that names no model sends no `model`, and the server answers with its default.
  *
  * ## Deliberately not React, and deliberately not react-query
  *
- * `packages/app` reads the same surface through `useCatalogue`, a react-query
- * hook. The SDK cannot copy that: it declares `@tanstack/react-query` as a
- * dependency but imports it in **zero** modules today — measured — so a consumer
- * mounting `<AliaChatSheet>` is not required to have a `QueryClientProvider`
- * anywhere above it. Introducing one here would turn "the model default came
- * from the server" into a breaking change for every consumer, which is a bad
- * trade for a fallback.
+ * The SDK imports `@tanstack/react-query` in no module, so a consumer mounting
+ * `<AliaChatSheet>` is not required to have a `QueryClientProvider`. Resolution
+ * happens inside `send`, at the moment a request is about to name a model, and a
+ * module-level cache keeps that from becoming a fetch per message.
  *
- * Resolution therefore happens where it matters — inside `send`, at the moment a
- * request is about to name a model — rather than at render. A module-level cache
- * keeps that from becoming a fetch per message.
+ * ## Parsing does not invent
  *
- * ## The parsing rules are the app's, because the contract is the same one
- *
- * Two rules, both about not inventing (see `packages/app/lib/hooks/use-catalogue.ts`,
- * which states them at length):
- *
- *  - An entry whose `object` is neither known value is DROPPED. Defaulting it to
- *    either kind would break ADR 0003 invariant 1 in one direction or the other.
- *  - A response whose entries all fail to parse THROWS rather than reading as an
- *    empty catalogue, because "no models" and "we could not read the models"
- *    look identical to every caller below and one of them means "offer nothing".
- *
- * This file is a second implementation of that contract rather than a shared
- * one, and that is forced rather than chosen: `@alia.onl/sdk` ships as raw
- * source, so it cannot depend on an unpublished workspace package — a consumer's
- * Metro would fail to resolve it. The three Node-side clients (Codea, Cowork,
- * the CLI) share one instead.
+ * An entry without an id or a name is dropped, and a response whose entries all
+ * fail to parse THROWS rather than reading as an empty catalogue: "no models"
+ * and "we could not read the models" look identical to every caller below, and
+ * one of them means "offer nothing".
  */
 
-/** A product-owned policy that picks a model per request, or a reference to one named model. */
-export type CatalogueEntryKind = 'routing_profile' | 'model';
+/** A reasoning effort a model accepts. */
+export type ReasoningEffort = 'low' | 'medium' | 'high';
+
+const REASONING_EFFORTS: readonly ReasoningEffort[] = ['low', 'medium', 'high'];
 
 export interface CatalogueEntry {
+  /** `publisher/model`. */
   readonly id: string;
-  readonly kind: CatalogueEntryKind;
-  readonly displayName: string;
-  readonly description: string;
-  /** Product policy: whether a chat picker surfaces this entry. */
-  readonly chatVisible: boolean;
-  /** The server states this as a claim; an entry that omits it is not called unavailable. */
-  readonly unavailable: boolean;
+  readonly name: string;
+  readonly publisher: { readonly id: string; readonly name: string };
+  readonly description: string | null;
+  readonly contextWindow: number | null;
+  readonly maxOutput: number | null;
+  readonly inputModalities: readonly string[];
+  readonly outputModalities: readonly string[];
+  readonly tools: boolean;
+  /** The efforts the model accepts, cheapest first. Empty: send none. */
+  readonly reasoningEfforts: readonly ReasoningEffort[];
+  readonly pricing: { readonly inputPerMTok: string; readonly outputPerMTok: string } | null;
+  readonly releasedAt: string | null;
+  readonly featured: boolean;
+}
+
+export interface Catalogue {
+  readonly entries: readonly CatalogueEntry[];
+  /** What a request without `model` is answered with, or `null` if the server did not say. */
+  readonly defaultModelId: string | null;
+  /** The ids a picker shows first, in order. */
+  readonly featuredIds: readonly string[];
 }
 
 type JsonObject = Record<string, unknown>;
@@ -64,7 +62,15 @@ function asObject(value: unknown): JsonObject | null {
 }
 
 function asText(value: unknown): string | null {
-  return typeof value === 'string' ? value : null;
+  return typeof value === 'string' && value !== '' ? value : null;
+}
+
+function asCount(value: unknown): number | null {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : null;
+}
+
+function asTexts(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((item): item is string => typeof item === 'string') : [];
 }
 
 function parseEntry(value: unknown): CatalogueEntry | null {
@@ -72,27 +78,41 @@ function parseEntry(value: unknown): CatalogueEntry | null {
   if (raw === null) return null;
 
   const id = asText(raw.id);
-  const displayName = asText(raw.display_name);
-  if (id === null || displayName === null) return null;
+  const name = asText(raw.name);
+  if (id === null || name === null) return null;
 
-  if (raw.object !== 'model' && raw.object !== 'routing_profile') return null;
-  const availability = asObject(raw.availability) ?? {};
+  const publisher = asObject(raw.publisher);
+  const publisherId = asText(publisher?.id) ?? id.split('/')[0] ?? id;
+  const pricing = asObject(raw.pricing);
+  const input = asText(pricing?.inputPerMTok);
+  const output = asText(pricing?.outputPerMTok);
 
   return {
     id,
-    kind: raw.object,
-    displayName,
-    description: asText(raw.description) ?? '',
-    chatVisible: raw.chat_visible === true,
-    unavailable: availability.status === 'unavailable',
+    name,
+    publisher: { id: publisherId, name: asText(publisher?.name) ?? publisherId },
+    description: asText(raw.description),
+    contextWindow: asCount(raw.contextWindow),
+    maxOutput: asCount(raw.maxOutput),
+    inputModalities: asTexts(raw.inputModalities),
+    outputModalities: asTexts(raw.outputModalities),
+    tools: raw.tools === true,
+    reasoningEfforts: REASONING_EFFORTS.filter((effort) =>
+      asTexts(raw.reasoningEfforts).includes(effort),
+    ),
+    pricing: input !== null && output !== null ? { inputPerMTok: input, outputPerMTok: output } : null,
+    releasedAt: asText(raw.releasedAt),
+    featured: raw.featured === true,
   };
 }
 
-/** Turn a catalogue response into entries, or throw. */
-export function parseCatalogue(payload: unknown): CatalogueEntry[] {
+/** Turn a catalogue response into a {@link Catalogue}, or throw. */
+export function parseCatalogue(payload: unknown): Catalogue {
   const body = asObject(payload);
   const data = body === null ? null : body.data;
-  if (!Array.isArray(data)) throw new Error('The model catalogue response could not be read.');
+  if (body === null || !Array.isArray(data)) {
+    throw new Error('The model catalogue response could not be read.');
+  }
 
   const entries: CatalogueEntry[] = [];
   for (const value of data) {
@@ -102,57 +122,53 @@ export function parseCatalogue(payload: unknown): CatalogueEntry[] {
   if (data.length > 0 && entries.length === 0) {
     throw new Error('The model catalogue response could not be read.');
   }
-  return entries;
+  return {
+    entries,
+    defaultModelId: asText(body.defaultModelId),
+    featuredIds: asTexts(body.featuredIds),
+  };
 }
 
 export interface ModelSelection {
-  /** What the caller asked for, which is what a picker keeps showing as chosen. */
-  readonly requestedId: string;
-  /** What a request should carry. Differs from `requestedId` only when replaced. */
-  readonly effectiveId: string;
+  /** What the caller asked for; `undefined` is "the server's default". */
+  readonly requestedId: string | undefined;
+  /** What a request should carry as `model`; `undefined` means omit it. */
+  readonly effectiveId: string | undefined;
+  /** The entry the request will be answered by, when the catalogue says. */
+  readonly entry: CatalogueEntry | null;
   /** `replaced` when the requested identifier is not one the catalogue offers. */
-  readonly source: 'requested' | 'replaced';
+  readonly source: 'requested' | 'default' | 'replaced';
 }
 
 /**
  * Resolve a requested identifier against the catalogue.
  *
- * The same three deliberate non-behaviours as the app's `resolveSelection`:
- *
+ *  - **Nothing requested** → omit `model`; the server's default answers.
  *  - **No catalogue — not loaded, or the request failed — leaves the choice
- *    alone.** Replacing on missing data changes the model under the user on any
- *    slow cold start, which is the same wrong answer as a retirement.
- *  - **An entry reported UNAVAILABLE is still honoured.** That is a health
- *    signal about the models behind an entry and the server already falls back
- *    among them; picking a different one is a product decision nobody made.
- *  - **`preferredId` is never trusted.** It is a build-time value, so it is
- *    checked against the catalogue like any other and falls through when the
- *    catalogue does not offer it.
+ *    alone.** Replacing on missing data would change the model under the user
+ *    on any slow cold start.
+ *  - **An identifier the catalogue no longer lists** is not sent (it would be
+ *    refused); the request omits `model` and the server's default answers.
  */
 export function resolveSelection(
-  requestedId: string,
-  entries: readonly CatalogueEntry[] | undefined,
-  preferredId?: string,
+  requestedId: string | null | undefined,
+  catalogue: Catalogue | undefined,
 ): ModelSelection {
-  if (entries === undefined) {
-    return { requestedId, effectiveId: requestedId, source: 'requested' };
-  }
+  const requested = requestedId === null || requestedId === '' ? undefined : requestedId;
+  const defaultEntry = (): CatalogueEntry | null =>
+    catalogue?.entries.find((entry) => entry.id === catalogue.defaultModelId) ?? null;
 
-  const offered = entries.filter((entry) => entry.chatVisible);
-  if (offered.some((entry) => entry.id === requestedId)) {
-    return { requestedId, effectiveId: requestedId, source: 'requested' };
+  if (requested === undefined) {
+    return { requestedId: undefined, effectiveId: undefined, entry: defaultEntry(), source: 'default' };
   }
-
-  const replacement =
-    (preferredId === undefined
-      ? undefined
-      : offered.find((entry) => entry.id === preferredId)) ??
-    offered.find((entry) => !entry.unavailable) ??
-    offered[0];
-  if (replacement === undefined) {
-    return { requestedId, effectiveId: requestedId, source: 'requested' };
+  if (catalogue === undefined) {
+    return { requestedId: requested, effectiveId: requested, entry: null, source: 'requested' };
+  }
+  const entry = catalogue.entries.find((candidate) => candidate.id === requested);
+  if (entry !== undefined) {
+    return { requestedId: requested, effectiveId: requested, entry, source: 'requested' };
   }
-  return { requestedId, effectiveId: replacement.id, source: 'replaced' };
+  return { requestedId: requested, effectiveId: undefined, entry: defaultEntry(), source: 'replaced' };
 }
 
 /**
@@ -162,9 +178,9 @@ export function resolveSelection(
  * request. A REJECTED promise is evicted, because caching a failure would make a
  * single cold-start network blip permanent for the life of the process.
  */
-const inFlight = new Map<string, Promise<CatalogueEntry[]>>();
+const inFlight = new Map<string, Promise<Catalogue>>();
 
-export function fetchCatalogue(apiUrl: string, accessToken?: string): Promise<CatalogueEntry[]> {
+export function fetchCatalogue(apiUrl: string, accessToken?: string): Promise<Catalogue> {
   const cached = inFlight.get(apiUrl);
   if (cached !== undefined) return cached;
 
@@ -187,23 +203,20 @@ export function clearCatalogueCache(): void {
 }
 
 /**
- * The identifier a request should carry, given what the caller asked for.
+ * The `model` a request should carry, given what the caller asked for, or
+ * `undefined` to omit it and let the server's default answer.
  *
  * Never throws: a catalogue that cannot be read leaves the requested identifier
- * alone, which is the same answer as "the catalogue has not loaded yet". A
- * consumer that wants to KNOW the catalogue is unreadable calls
- * {@link fetchCatalogue} directly.
+ * alone, which is the same answer as "the catalogue has not loaded yet".
  */
 export async function resolveModelId(
   apiUrl: string,
-  requestedId: string,
+  requestedId: string | undefined,
   accessToken?: string,
-  preferredId?: string,
-): Promise<string> {
-  if (requestedId.startsWith('mode:')) return requestedId;
+): Promise<string | undefined> {
+  if (requestedId === undefined || requestedId === '') return undefined;
   try {
-    const entries = await fetchCatalogue(apiUrl, accessToken);
-    return resolveSelection(requestedId, entries, preferredId).effectiveId;
+    return resolveSelection(requestedId, await fetchCatalogue(apiUrl, accessToken)).effectiveId;
   } catch {
     return requestedId;
   }

package/src/lib/chat-stream.ts

@@ -177,11 +177,6 @@ function validateIgnoredNamedEvent(eventName: string, payload: JsonObject): void
   requireEventVersion(payload, eventName);
 
   switch (eventName) {
-    case 'alia.model_switch':
-      assertOnlyKeys(payload, ['eventVersion', 'model', 'modelName'], eventName);
-      asString(payload.model, `${eventName} model`);
-      asString(payload.modelName, `${eventName} modelName`);
-      return;
     case 'alia.suggest_new_conversation':
       assertOnlyKeys(payload, ['eventVersion', 'reason'], eventName);
       asString(payload.reason, `${eventName} reason`);

package/src/lib/chat-transport.ts

@@ -16,8 +16,18 @@ export interface AuthenticatedResponseClient {
 
 export interface AliaChatRequest {
   readonly url: string;
-  readonly model: string;
+  /** `publisher/model`; omitted, the server's default model answers. */
+  readonly model?: string;
   readonly messages: ReadonlyArray<{ readonly role: string; readonly content: string }>;
+  /**
+   * `'voice'` asks for an answer meant to be heard: short, conversational, no
+   * formatting (the API layers its voice response profile over the turn's
+   * prompt). Omitted for ordinary text chat, which sends exactly what it
+   * always sent.
+   */
+  readonly responseMode?: 'voice';
+  /** The agent whose thread this turn belongs to, when there is one. */
+  readonly agentId?: string;
 }
 
 /**
@@ -39,9 +49,11 @@ export async function streamAliaChat(
       'Content-Type': 'application/json',
     },
     body: JSON.stringify({
-      model: request.model,
+      ...(request.model === undefined ? {} : { model: request.model }),
       messages: request.messages,
       stream: true,
+      ...(request.responseMode === undefined ? {} : { responseMode: request.responseMode }),
+      ...(request.agentId === undefined ? {} : { agentId: request.agentId }),
     }),
     signal,
   });

package/src/lib/speech-language.ts

@@ -0,0 +1,20 @@
+/**
+ * The language to recognize when the caller names none.
+ *
+ * The browser's own language on web; the runtime's resolved locale on native
+ * (Hermes implements `Intl`); `en-US` when neither answers. An app should pass
+ * its UI locale instead — the Alia app does — because a person who chose
+ * Spanish in the app expects to be understood in Spanish whatever the device
+ * is set to.
+ */
+export function defaultSpeechLanguage(): string {
+  const browser = globalThis.navigator?.language;
+  if (typeof browser === 'string' && browser !== '') return browser;
+  try {
+    const resolved = Intl.DateTimeFormat().resolvedOptions().locale;
+    if (resolved) return resolved;
+  } catch {
+    // No Intl on this runtime.
+  }
+  return 'en-US';
+}

package/src/lib/speech-messages.ts

@@ -0,0 +1,76 @@
+import type { SpeechRecognitionFailure } from './speech-recognition-types';
+
+/**
+ * Every way dictation or a voice call can fail that a person is told about,
+ * as a stable code.
+ *
+ * The hooks expose the code beside the English sentence (`errorCode` /
+ * `turnErrorCode` next to `error` / `turnError`) so an app can say it in its
+ * own language; the sentence stays for a consumer that has no translations.
+ */
+export type VoiceErrorCode =
+  | 'speech-unsupported'
+  | 'microphone-denied'
+  | 'microphone-busy'
+  | 'microphone-missing'
+  | 'speech-network'
+  | 'speech-language'
+  | 'speech-failed'
+  | 'voice-unavailable'
+  | 'not-authenticated'
+  | 'turn-failed'
+  | 'no-answer'
+  | 'not-played';
+
+/**
+ * The English copy for each code — the same sentences dictation and voice mode
+ * used when they recorded through `expo-audio` and LiveKit, so moving
+ * recognition onto the device did not change what an error says.
+ */
+export const VOICE_ERROR_MESSAGES: Readonly<Record<VoiceErrorCode, string>> = {
+  'speech-unsupported': 'Speech recognition is not available on this device or browser',
+  'microphone-denied': 'Microphone permission required',
+  'microphone-busy': 'Microphone is in use by another application',
+  'microphone-missing': 'No microphone found — check your input devices',
+  'speech-network': 'Speech recognition needs a network connection',
+  'speech-language': 'Speech recognition does not support this language',
+  'speech-failed': 'Speech recognition failed',
+  'voice-unavailable': 'Voice is not available on this device',
+  'not-authenticated': 'Not authenticated',
+  'turn-failed': 'Voice request failed',
+  'no-answer': 'No answer came back — try saying it again',
+  'not-played': 'The answer could not be played aloud',
+};
+
+/**
+ * The code for a recognition failure. `null` for the failures that are not
+ * errors: `aborted` is a stop the caller asked for, and `no-speech` is a
+ * silence the caller recovers from.
+ */
+export function speechFailureCode(failure: SpeechRecognitionFailure): VoiceErrorCode | null {
+  switch (failure.code) {
+    case 'aborted':
+    case 'no-speech':
+      return null;
+    case 'unsupported':
+      return 'speech-unsupported';
+    case 'not-allowed':
+      return 'microphone-denied';
+    case 'audio-capture':
+      return failure.detail === 'NotReadableError' || failure.detail === 'TrackStartError'
+        ? 'microphone-busy'
+        : 'microphone-missing';
+    case 'network':
+      return 'speech-network';
+    case 'language-not-supported':
+      return 'speech-language';
+    case 'other':
+      return 'speech-failed';
+  }
+}
+
+/** The English copy a person sees when listening fails; `null` as for `speechFailureCode`. */
+export function speechFailureMessage(failure: SpeechRecognitionFailure): string | null {
+  const code = speechFailureCode(failure);
+  return code === null ? null : VOICE_ERROR_MESSAGES[code];
+}

package/src/lib/speech-recognition-types.ts

@@ -0,0 +1,108 @@
+/**
+ * The one shape on-device speech recognition has in this package.
+ *
+ * Two engines sit behind it and neither leaks through: the browser's Web
+ * Speech API (`speech-recognition.ts`, picked by web bundlers and by tests) and
+ * `expo-speech-recognition` on iOS and Android (`speech-recognition.native.ts`,
+ * picked by Metro's platform resolution). Dictation and the voice loop are
+ * written against this file only, so the audio never leaves the device through
+ * Alia — there is no transcription endpoint, and nothing here posts audio
+ * anywhere. Whether the ENGINE uses a network service is the platform's
+ * business and is stated in `docs/voice.mdx`.
+ */
+
+/** Why a recognition session failed, in the vocabulary both engines share. */
+export type SpeechRecognitionFailureCode =
+  /** Microphone or speech-recognition permission was refused. */
+  | 'not-allowed'
+  /** No microphone, or it could not be opened. */
+  | 'audio-capture'
+  /** The engine needed the network and could not reach it. */
+  | 'network'
+  /** The engine does not recognize this language. */
+  | 'language-not-supported'
+  /** Nothing was said before the engine gave up. Recoverable: start again. */
+  | 'no-speech'
+  /** The session was aborted on purpose. Never an error to report. */
+  | 'aborted'
+  /** Recognition is not available on this device or in this browser. */
+  | 'unsupported'
+  /** Anything else — the engine was busy, interrupted, or said nothing useful. */
+  | 'other';
+
+export interface SpeechRecognitionFailure {
+  readonly code: SpeechRecognitionFailureCode;
+  /** The engine's own words, for logs. Never shown as-is. */
+  readonly detail?: string;
+}
+
+export interface SpeechRecognitionHandlers {
+  /**
+   * The whole of what this session has heard so far, and whether the engine
+   * considers it settled. It is the FULL transcript each time, never a delta:
+   * both engines revise earlier words as more audio arrives.
+   */
+  onResult(result: { transcript: string; isFinal: boolean }): void;
+  /** Input level, 0..1, on the same scale as dictation's metering. */
+  onLevel?(level: number): void;
+  onError(failure: SpeechRecognitionFailure): void;
+  /** The session is over, whichever way it ended. Always the last call. */
+  onEnd(): void;
+}
+
+export interface SpeechRecognitionOptions {
+  /** BCP-47 tag, e.g. `es-ES`. */
+  readonly lang: string;
+  /**
+   * Android: the recognition service to use, by package, instead of the
+   * system's default. `chooseSpeechRecognizer` picks it.
+   */
+  readonly service?: string;
+  /**
+   * Remove the device's own playback from what the microphone hears, where the
+   * platform can (iOS voice processing). Voice mode listens while it speaks,
+   * so without this it can hear itself.
+   */
+  readonly echoCancellation?: boolean;
+}
+
+export interface SpeechRecognitionSession {
+  /** Stop listening and deliver a final result, then `onEnd`. */
+  stop(): void;
+  /** Stop listening and discard; `onEnd` still follows. */
+  abort(): void;
+}
+
+/** Map a raw 0..1-ish reading to the field's level, clamped. */
+export function clampLevel(level: number): number {
+  if (!Number.isFinite(level)) return 0;
+  return Math.min(1, Math.max(0, level));
+}
+
+/**
+ * What to start a session with, decided before the first one opens.
+ *
+ * `silent` is set when the device has recognition services and every one of
+ * them, asked, named no language at all. A `language-not-supported` from such
+ * a device is not about the language: nothing on it recognizes speech (a Pixel
+ * without Google's speech services, whose remaining service has no language
+ * pack). Where nobody could be asked — the web, iOS — it is `false` and a
+ * language error stays one.
+ */
+export type SpeechRecognizerChoice =
+  | { readonly lang: string; readonly service?: string; readonly silent: boolean }
+  | { readonly failure: SpeechRecognitionFailure };
+
+/**
+ * The tag in `offered` that recognizes `lang`: the same tag (`en-US`, however
+ * the service spells it — `en_US`, `en-us`), else another region of the same
+ * language (`es-US` for `es-ES`), else `null`.
+ */
+export function matchSpeechLocale(lang: string, offered: readonly string[]): string | null {
+  const norm = (tag: string) => tag.replace(/_/g, '-').toLowerCase();
+  const wanted = norm(lang);
+  const exact = offered.find((tag) => norm(tag) === wanted);
+  if (exact !== undefined) return exact;
+  const language = wanted.split('-')[0];
+  return offered.find((tag) => norm(tag).split('-')[0] === language) ?? null;
+}