@kabmo-labs/kabmo 0.0.0-stage → 0.1.0

package/src/shared/lib/code/syntax-highlight.ts

@@ -0,0 +1,207 @@
+import type { HighlighterCore } from 'shiki/core';
+
+import { escapeCode, getHighlighterSync, requestLanguage } from '@/shared/lib/code/highlighter';
+import { tokenMarkup, type HighlightLinesOptions } from '@/shared/lib/code/editor/marks';
+import { lineStartOffset } from '@/shared/lib/code/editor/lines';
+import { SHIKI_THEMES } from '@/shared/lib/code/shiki-themes';
+
+export type { HighlightLinesOptions };
+
+
+/**
+ * Pick a language that can be tokenized *synchronously* right now. A grammar
+ * that has not arrived yet is requested here (fire-and-forget) and the caller
+ * falls back to javascript for this pass — `onLanguageReady` re-runs the
+ * highlight once it lands. `getLoadedLanguages()` stays the authority for
+ * embedded/alias names that `LANG_LOADERS` does not list by id.
+ */
+function resolveReadyLang(hl: HighlighterCore, language: string): string {
+  if (requestLanguage(language) || hl.getLoadedLanguages().includes(language)) return language;
+  return 'javascript';
+}
+
+/** Syntax highlight code string safely with fallback */
+export function highlightCode(code: string, language = 'javascript', options: HighlightLinesOptions = {}): string {
+  if (!code) return '';
+  // A find in progress needs the match markup, which only the line-based path
+  // emits; without it the fast `codeToHtml` path is left exactly as it was.
+  if (options.marks && options.marks.length > 0) {
+    return `<span class="shiki">${highlightLines(code, language, options).join('\n')}</span>`;
+  }
+  const hl = getHighlighterSync();
+  if (!hl) return escapeCode(code);
+  const lang = resolveReadyLang(hl, language);
+  try {
+    return `<span class="shiki">${hl.codeToHtml(code, {
+      lang,
+      themes: SHIKI_THEMES,
+      defaultColor: false,
+      structure: 'inline',
+    })}</span>`;
+  } catch {
+    return escapeCode(code);
+  }
+}
+
+export interface JsonDetectionResult {
+  isValid: boolean;
+  data?: any;
+  pretty?: string;
+  linesCount?: number;
+}
+
+/** Check if input is valid JSON (or object/array) and return pretty-printed string with line count */
+export function tryParseJson(input: unknown): JsonDetectionResult {
+  if (input === null || input === undefined) return { isValid: false };
+
+  // 1. If already an object or array (and not primitive)
+  if (typeof input === 'object') {
+    try {
+      const pretty = JSON.stringify(input, null, 2);
+      const linesCount = pretty.split('\n').length;
+      return { isValid: true, data: input, pretty, linesCount };
+    } catch {
+      return { isValid: false };
+    }
+  }
+
+  if (typeof input !== 'string') return { isValid: false };
+
+  let text = input.trim();
+  if (!text) return { isValid: false };
+
+  // 2. If wrapped in markdown code fence ```json ... ``` or ``` ... ```
+  const codeBlockMatch = text.match(/^```(?:json)?\s*([\s\S]*?)\s*```$/i);
+  if (codeBlockMatch) {
+    text = codeBlockMatch[1].trim();
+  }
+
+  // 3. Strip common prefixes like "User selected: { ... }" or "User response: { ... }"
+  const prefixMatch = text.match(/^(?:user\s+(?:selected|responded|answered|response)|response|result|output):\s*([\s\S]+)$/i);
+  if (prefixMatch) {
+    const candidate = prefixMatch[1].trim();
+    if ((candidate.startsWith('{') && candidate.endsWith('}')) || (candidate.startsWith('[') && candidate.endsWith(']'))) {
+      text = candidate;
+    }
+  }
+
+  // 4. Handle double-stringified / quoted JSON strings, e.g. "\"{\\\"a\\\":1}\"" or '"{...}"'
+  if ((text.startsWith('"') && text.endsWith('"')) || (text.startsWith("'") && text.endsWith("'"))) {
+    try {
+      const unquoted = JSON.parse(text);
+      if (typeof unquoted === 'object' && unquoted !== null) {
+        const pretty = JSON.stringify(unquoted, null, 2);
+        return { isValid: true, data: unquoted, pretty, linesCount: pretty.split('\n').length };
+      }
+      if (typeof unquoted === 'string') {
+        const nested = tryParseJson(unquoted);
+        if (nested.isValid) return nested;
+      }
+    } catch {
+      // not double-quoted JSON, continue
+    }
+  }
+
+  // 5. Check if starts with { or [
+  if (text.startsWith('{') || text.startsWith('[')) {
+    try {
+      const data = JSON.parse(text);
+      if (data !== null && typeof data === 'object') {
+        const pretty = JSON.stringify(data, null, 2);
+        const linesCount = pretty.split('\n').length;
+        return { isValid: true, data, pretty, linesCount };
+      }
+    } catch {
+      // not direct JSON
+    }
+  }
+
+  // 6. Look for embedded JSON object/array within text: e.g. "Response: {...}"
+  const firstBrace = text.indexOf('{');
+  const lastBrace = text.lastIndexOf('}');
+  if (firstBrace !== -1 && lastBrace > firstBrace) {
+    const candidate = text.slice(firstBrace, lastBrace + 1);
+    try {
+      const data = JSON.parse(candidate);
+      if (data !== null && typeof data === 'object') {
+        const pretty = JSON.stringify(data, null, 2);
+        return { isValid: true, data, pretty, linesCount: pretty.split('\n').length };
+      }
+    } catch {
+      // ignore
+    }
+  }
+
+  const firstBracket = text.indexOf('[');
+  const lastBracket = text.lastIndexOf(']');
+  if (firstBracket !== -1 && lastBracket > firstBracket) {
+    const candidate = text.slice(firstBracket, lastBracket + 1);
+    try {
+      const data = JSON.parse(candidate);
+      if (Array.isArray(data)) {
+        const pretty = JSON.stringify(data, null, 2);
+        return { isValid: true, data, pretty, linesCount: pretty.split('\n').length };
+      }
+    } catch {
+      // ignore
+    }
+  }
+
+  return { isValid: false };
+}
+
+/** Syntax highlight JSON string */
+export function highlightJson(code: string): string {
+  return highlightCode(code, 'json');
+}
+
+/**
+ * Highlight code and return one HTML fragment per line, aligned 1:1 with
+ * `code.split('\n')`. Tokenizes the whole input at once so multi-line grammar
+ * state (block comments, template literals) survives, unlike per-line calls.
+ */
+export function highlightLines(
+  code: string,
+  language = 'javascript',
+  options: HighlightLinesOptions = {},
+): string[] {
+  const rawLines = code.split('\n');
+  const marks = options.marks;
+  const currentMark = options.currentMark ?? -1;
+  const occurrenceFrom = options.occurrenceFrom ?? -1;
+  // A grammar that has not arrived yet, or a highlighter that failed to boot,
+  // still gets the find marks: the widget's feedback must not depend on Shiki.
+  const plain = (lineIndex: number): string => {
+    if (!marks || marks.length === 0) return escapeCode(rawLines[lineIndex]);
+    return tokenMarkup(rawLines[lineIndex], lineStartOffset(code, lineIndex), marks, currentMark, occurrenceFrom);
+  };
+  if (!code) return rawLines;
+  const hl = getHighlighterSync();
+  if (!hl) return rawLines.map((_line, index) => plain(index));
+  const lang = resolveReadyLang(hl, language);
+  try {
+    const { tokens } = hl.codeToTokens(code, {
+      lang,
+      themes: SHIKI_THEMES,
+      defaultColor: false,
+      tokenizeMaxLineLength: options.maxLineLength ?? 0,
+    });
+    if (tokens.length !== rawLines.length) return rawLines.map((_line, index) => plain(index));
+    return tokens.map((lineTokens, lineIndex) => {
+      let offset = lineStartOffset(code, lineIndex);
+      return lineTokens
+        .map((tok) => {
+          const content = tokenMarkup(tok.content, offset, marks, currentMark, occurrenceFrom);
+          offset += tok.content.length;
+          if (!tok.htmlStyle) return content;
+          const style = Object.entries(tok.htmlStyle)
+            .map(([key, value]) => `${key}:${value}`)
+            .join(';');
+          return style ? `<span style="${style}">${content}</span>` : content;
+        })
+        .join('');
+    });
+  } catch {
+    return rawLines.map((_line, index) => plain(index));
+  }
+}

package/src/shared/lib/code/windowed-highlight.ts

@@ -0,0 +1,114 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { LineWindow } from '@/shared/lib/code/lazy-window';
+import type { FindMatch } from '@/shared/lib/code/editor/find';
+import { lineStartOffset } from '@/shared/lib/code/editor/lines';
+import { highlightLines } from '@/shared/lib/code/syntax-highlight';
+
+/**
+ * Lines tokenized *above* the window and dropped from the result. They only
+ * seed the grammar state, so a window that starts inside a block comment or a
+ * template literal still tokenizes as a comment / template literal. Tokenizing
+ * them costs a fraction of the window itself; carrying the whole document as
+ * context would defeat the point of windowing at all.
+ */
+const CONTEXT_LINES = 40;
+
+/**
+ * Lines at or above this length render as plain text. A minified bundle is one
+ * line of hundreds of KB, which the tokenizer would chew through on every
+ * scroll; the cap keeps that bounded, exactly like Shiki's own
+ * `tokenizeMaxLineLength` bail-out.
+ */
+const MAX_LINE_CHARS = 12_000;
+
+export interface HighlightCodeWindowOptions {
+  /** Lines of grammar context above the window. */
+  contextLines?: number;
+  /** Length at which a line falls back to plain text. */
+  maxLineLength?: number;
+  /**
+   * Find matches in DOCUMENT offsets. Only those inside the rendered window are
+   * passed on, re-based to the sliced source the tokenizer sees.
+   */
+  marks?: readonly FindMatch[];
+  /** Index of the current match within `marks`. */
+  currentMark?: number;
+  /** Marks from this index on are extra ⌘D selections rather than find matches. */
+  occurrenceFrom?: number;
+}
+
+/**
+ * Shiki markup for lines `[window.start, window.end)` of `code`, joined with
+ * newlines so it can be dropped straight into the editor's `<pre>`. The caller
+ * reserves the space of the lines it is not given (`lazy-window`'s
+ * `windowSpace`), which is what keeps the caret over its own row.
+ *
+ * The rows are wrapped in `.shiki` — the app colours tokens through the
+ * `.shiki span { color: var(--shiki-light) }` rule (`tailwind.css`), so markup
+ * that skipped the wrapper would render in the plain ink colour. Every other
+ * consumer of `highlightLines` carries the same class.
+ *
+ * Editing is unaffected: the `<textarea>` above the highlight layer always
+ * holds the full document — only the markup is windowed.
+ */
+export function highlightCodeWindow(
+  code: string,
+  language: string,
+  window: LineWindow,
+  options: HighlightCodeWindowOptions = {},
+): string {
+  const { contextLines = CONTEXT_LINES, maxLineLength = MAX_LINE_CHARS } = options;
+  const lines = code.split('\n');
+  const start = Math.min(Math.max(window.start, 0), lines.length);
+  const end = Math.min(Math.max(window.end, start), lines.length);
+  if (start === end) return '';
+
+  const contextStart = Math.max(0, start - contextLines);
+  const slice = lines.slice(contextStart, end).join('\n');
+  const base = lineStartOffset(code, contextStart);
+  const sliceEnd = base + slice.length;
+  const { marks, currentMark, occurrenceFrom } = rebaseMarks(
+    options.marks,
+    options.currentMark ?? -1,
+    options.occurrenceFrom ?? -1,
+    base,
+    sliceEnd,
+  );
+  const rows = highlightLines(slice, language, { maxLineLength, marks, currentMark, occurrenceFrom });
+  const offset = start - contextStart;
+  return `<span class="shiki">${rows.slice(offset, offset + (end - start)).join('\n')}</span>`;
+}
+
+/**
+ * The marks inside `[base, sliceEnd)`, shifted to slice coordinates, with the
+ * current-match index remapped — the index points into the full list, so the
+ * rows below the window cannot simply reuse it.
+ */
+function rebaseMarks(
+  marks: readonly FindMatch[] | undefined,
+  currentMark: number,
+  occurrenceFrom: number,
+  base: number,
+  sliceEnd: number,
+): { marks: FindMatch[]; currentMark: number; occurrenceFrom: number } {
+  if (!marks || marks.length === 0) return { marks: [], currentMark: -1, occurrenceFrom: -1 };
+  const kept: FindMatch[] = [];
+  let remapped = -1;
+  let remappedOccurrenceFrom = -1;
+  for (let index = 0; index < marks.length; index++) {
+    const mark = marks[index];
+    if (mark.end <= base) continue;
+    if (mark.start >= sliceEnd) break;
+    if (index === currentMark) remapped = kept.length;
+    // The first surviving occurrence keeps the split, wherever it landed: a
+    // window whose opening lines held only matches still has to paint the
+    // selections below them differently.
+    if (remappedOccurrenceFrom === -1 && occurrenceFrom >= 0 && index >= occurrenceFrom) remappedOccurrenceFrom = kept.length;
+    kept.push({ start: mark.start - base, end: Math.min(mark.end, sliceEnd) - base });
+  }
+  return { marks: kept, currentMark: remapped, occurrenceFrom: remappedOccurrenceFrom };
+}

package/src/shared/lib/db/transaction.server.ts

@@ -0,0 +1,20 @@
+import type { DbClient } from '@/server/lib/db/client';
+
+/**
+ * Run `fn` inside a BEGIN…COMMIT block.
+ *
+ * `bun:sqlite` is synchronous, so the promise-chain mutex the old async driver
+ * needed is gone: a transaction block runs to completion before any other
+ * JavaScript executes, which makes `BEGIN`…`COMMIT` atomic by construction.
+ */
+export function withTransaction<T>(db: DbClient, fn: () => T): T {
+  db.raw.exec('BEGIN');
+  try {
+    const result = fn();
+    db.raw.exec('COMMIT');
+    return result;
+  } catch (error) {
+    db.raw.exec('ROLLBACK');
+    throw error;
+  }
+}

package/src/shared/lib/dictation/audio.ts

@@ -0,0 +1,75 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Audio conversion for dictation.
+ *
+ * Three formats meet in this feature, and mixing them up is the failure mode
+ * that costs an afternoon:
+ * - **Float32, ±1** — what omp's STT worker takes. It hands the array straight
+ *   to the transformers.js feature extractor, which rejects anything else
+ *   ("WhisperFeatureExtractor expects input to be a Float32Array ... but got
+ *   Uint8Array"), and treats a STRING as an encoded file to decode — which
+ *   needs `AudioContext` and fails in the worker ("Unable to load audio from
+ *   path/URL since `AudioContext` is not available in your environment").
+ *   Verified against omp 18.4.10: only a Float32Array transcribes.
+ * - **PCM16LE** — the wire format, half the bytes of Float32.
+ * - **Float32 at the device rate** — what `AudioContext` hands the capture
+ *   callback, usually 48 kHz, so it needs resampling on the way out.
+ */
+
+/** Normalized Float32 samples from mono PCM16LE bytes. */
+export function pcm16ToFloat32(bytes: Uint8Array): Float32Array {
+  // An odd byteOffset cannot back an Int16Array; copy when the view is unaligned.
+  const aligned =
+    bytes.byteOffset % 2 === 0
+      ? new Int16Array(bytes.buffer, bytes.byteOffset, bytes.byteLength >> 1)
+      : new Int16Array(bytes.slice().buffer, 0, bytes.byteLength >> 1);
+  const out = new Float32Array(aligned.length);
+  for (let i = 0; i < aligned.length; i++) {
+    out[i] = aligned[i] / 32768;
+  }
+  return out;
+}
+
+/** Mono PCM16LE from Float32 samples, resampled to `outputRate` when needed. */
+export function float32ToPcm16(
+  input: Float32Array,
+  inputRate: number,
+  outputRate: number,
+): Int16Array {
+  const ratio = inputRate === outputRate ? 1 : inputRate / outputRate;
+  const outLength = ratio === 1 ? input.length : Math.round(input.length / ratio);
+  const out = new Int16Array(outLength);
+
+  for (let i = 0; i < outLength; i++) {
+    let sample: number;
+    if (ratio === 1) {
+      sample = input[i];
+    } else {
+      // Linear interpolation. The STT front-end re-frames to its own mel bins,
+      // so a sharper kernel buys nothing audible.
+      const pos = i * ratio;
+      const lo = Math.min(Math.floor(pos), input.length - 1);
+      const hi = Math.min(lo + 1, input.length - 1);
+      sample = input[lo] + (input[hi] - input[lo]) * (pos - lo);
+    }
+    const clamped = sample < -1 ? -1 : sample > 1 ? 1 : sample;
+    out[i] = clamped < 0 ? clamped * 0x8000 : clamped * 0x7fff;
+  }
+  return out;
+}
+
+/** Concatenate capture chunks into one contiguous sample buffer. */
+export function concatSamples(chunks: readonly Float32Array[]): Float32Array {
+  const total = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
+  const merged = new Float32Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    merged.set(chunk, offset);
+    offset += chunk.length;
+  }
+  return merged;
+}

package/src/shared/lib/dictation/models.test.ts

@@ -0,0 +1,95 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * `summarizeProgress` decides what the composer's status line says while a
+ * first-run model download runs, and the rule it encodes is not obvious from
+ * the event shapes: omp reports TWO different quantities under the same
+ * `progress` field — `progress_total` is the percent of the whole download,
+ * `progress` is the percent of one file. Taking the per-file value as the
+ * overall figure makes the number jump backwards every time the download moves
+ * to the next file.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { STT_MODELS, isSttModelKey, summarizeProgress } from '@/shared/lib/dictation/models';
+
+/**
+ * omp 18.11.0 `STT_MODEL_VALUES`. The worker answers `Unknown stt model` for
+ * anything outside this set, and a key missing here is unreachable from the
+ * composer — `nemotron-streaming-en-0.6b` (added in 18.11.0) was exactly that.
+ */
+const OMP_STT_MODEL_KEYS: readonly string[] = [
+  'whisper-base',
+  'whisper-small',
+  'whisper-large-v3-turbo',
+  'parakeet-tdt-0.6b-v3',
+  'nemotron-streaming-en-0.6b',
+];
+
+describe('STT model keys mirror omp’s registry', () => {
+  test('every key omp serves is offered, and none omp would reject', () => {
+    const offered: string[] = STT_MODELS.map((model) => model.key);
+    expect(offered.sort()).toEqual([...OMP_STT_MODEL_KEYS].sort());
+  });
+
+  test('the 18.11.0 addition is accepted by the guard, not silently defaulted', () => {
+    expect(isSttModelKey('nemotron-streaming-en-0.6b')).toBe(true);
+    expect(isSttModelKey('whisper-base')).toBe(true);
+    expect(isSttModelKey('not-a-model')).toBe(false);
+  });
+
+  test('the two English-only tiers are marked as such', () => {
+    // Parakeet v3 is 25 European languages; Nemotron is English. Both ignore a
+    // `language` hint, so a user picking either for another language is
+    // choosing a model that cannot serve it.
+    const byKey = Object.fromEntries(STT_MODELS.map((model) => [model.key, model]));
+    expect(byKey['nemotron-streaming-en-0.6b'].multilingual).toBe(false);
+    expect(byKey['parakeet-tdt-0.6b-v3'].multilingual).toBe(false);
+    expect(byKey['whisper-base'].multilingual).toBe(true);
+  });
+});
+
+describe('summarizeProgress', () => {
+  test('a progress_total value is already a percent', () => {
+    // Measured shape: progress 0.00282 alongside loaded 2243 / total 79664191.
+    const summary = summarizeProgress({ status: 'progress_total', progress: 42 });
+    expect(summary.percent).toBe(42);
+    expect(summary.decoding).toBe(false);
+  });
+
+  test('a retrying download reports no figure rather than a stuck 100', () => {
+    // `loaded` accumulates across attempts while `total` stays fixed, so a real
+    // first-run fetch reached 2654 while files were still arriving. Pinning
+    // that at 100 would sit on screen for the whole download and read as
+    // "finished but stuck", so it becomes indeterminate instead.
+    expect(summarizeProgress({ status: 'progress_total', progress: 2654 }).percent).toBeNull();
+    expect(summarizeProgress({ status: 'progress_total', progress: -3 }).percent).toBeNull();
+  });
+
+  test('a figure inside 0..100 is shown', () => {
+    expect(summarizeProgress({ status: 'progress_total', progress: 100 }).percent).toBe(100);
+    expect(summarizeProgress({ status: 'progress_total', progress: 0 }).percent).toBe(0);
+  });
+
+  test('a per-file percent never becomes the overall figure', () => {
+    // 27.45 is one file's completion; taken as the total it would show 27%
+    // right after the total had already reported 86%.
+    const summary = summarizeProgress({ status: 'progress', file: 'tokenizer.json', progress: 27.45 });
+    expect(summary.percent).toBeNull();
+    expect(summary.decoding).toBe(false);
+  });
+
+  test('an in-flight file reports no percent but is still a download', () => {
+    const summary = summarizeProgress({ status: 'download', file: 'onnx/encoder_model_quantized.onnx' });
+    expect(summary.percent).toBeNull();
+    expect(summary.decoding).toBe(false);
+  });
+
+  test('once the files are fetched the wait is decoding, not downloading', () => {
+    expect(summarizeProgress({ status: 'ready' }).decoding).toBe(true);
+    expect(summarizeProgress({ status: 'done', file: 'config.json' }).decoding).toBe(true);
+  });
+});

package/src/shared/lib/dictation/models.ts

@@ -0,0 +1,139 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The speech-to-text models omp's own worker serves, and the shapes the
+ * Kabmo reports their download progress in.
+ *
+ * The keys are omp's (`STT_MODELS` in the CLI bundle) — passing anything else
+ * to the worker answers `Unknown stt model`. Labels and size hints mirror the
+ * options omp shows in its own settings, so the two surfaces describe the same
+ * set of models.
+ *
+ * `nemotron-streaming-en-0.6b` was added in omp 18.11.0. It is the one key the
+ * worker decodes through an ONLINE recognizer (`mode: "online"`), but that is
+ * omp's own streaming path (`stream_start`/`stream_audio`/`stream_stop`), which
+ * Kabmo does not drive — its socket sends one utterance per `transcribe`
+ * call. `decodeSegment` handles the online model on the BATCH path too
+ * (measured at 18.11.0: it feeds the utterance plus a terminal padding frame
+ * and returns the recognizer's text), so the key is offered here without a
+ * transport change; the label says what it is for so a user does not pick it
+ * expecting live words in this console.
+ */
+
+export type SttModelKey =
+  | 'whisper-base'
+  | 'whisper-small'
+  | 'whisper-large-v3-turbo'
+  | 'parakeet-tdt-0.6b-v3'
+  | 'nemotron-streaming-en-0.6b';
+
+export interface SttModel {
+  key: SttModelKey;
+  label: string;
+  sizeHint: string;
+  /** Parakeet v3 covers 25 European languages only; the Whisper tiers are multilingual. */
+  multilingual: boolean;
+}
+
+export const STT_MODELS: readonly SttModel[] = [
+  {
+    key: 'whisper-base',
+    label: 'Fast (Whisper base)',
+    sizeHint: '~80 MB',
+    multilingual: true,
+  },
+  {
+    key: 'whisper-small',
+    label: 'Balanced (Whisper small)',
+    sizeHint: '~250 MB',
+    multilingual: true,
+  },
+  {
+    key: 'whisper-large-v3-turbo',
+    label: 'Turbo (Whisper large-v3)',
+    sizeHint: '~500 MB',
+    multilingual: true,
+  },
+  {
+    key: 'parakeet-tdt-0.6b-v3',
+    label: 'Parakeet TDT v3 (SoTA)',
+    sizeHint: '~465 MB',
+    multilingual: false,
+  },
+  {
+    key: 'nemotron-streaming-en-0.6b',
+    label: 'Nemotron 0.6B (English, live in omp TUI)',
+    sizeHint: '~630 MB',
+    multilingual: false,
+  },
+];
+
+/**
+ * Default model. Deliberately the smallest MULTILINGUAL tier, not omp's own
+ * default (`parakeet-tdt-0.6b-v3`, 25 European languages): the common case here
+ * is a chat typed in a language Parakeet does not cover, and a first run that
+ * downloads 465 MB to transcribe it wrongly is the worst possible default.
+ */
+export const DEFAULT_STT_MODEL: SttModelKey = 'whisper-base';
+
+export function isSttModelKey(value: unknown): value is SttModelKey {
+  return typeof value === 'string' && STT_MODELS.some((model) => model.key === value);
+}
+
+/** One model's download/init progress, as omp's worker reports it. */
+export interface SttProgressEvent {
+  modelKey?: string;
+  status?: string;
+  name?: string;
+  file?: string;
+  /** 0..100 for the current file. */
+  progress?: number;
+  loaded?: number;
+  total?: number;
+}
+
+/** Compact progress for the client: percent + the file being fetched. */
+export interface SttProgressSummary {
+  /** 0..100 across the whole download, or null while no overall figure exists. */
+  percent: number | null;
+  file?: string;
+  /** True once the download is done and the utterance is being decoded. */
+  decoding: boolean;
+}
+
+/**
+ * Fold one worker progress event into what the composer shows.
+ *
+ * `progress_total` is the only event that covers the whole download, so it is
+ * the only one allowed to set the figure — `progress` describes a single file,
+ * and taking it as the total makes the number jump backwards at every file
+ * boundary.
+ *
+ * Its value is NOT dependable enough to pin at a ceiling, though. Measured on a
+ * real first-run fetch (omp 18.4.10, ~79 MB at ~68 KB/s): the figure reached
+ * 100 within the first eight seconds and then climbed past it to 2654 while the
+ * files were still arriving — `loaded` accumulates across retries while `total`
+ * stays fixed. A clamped 100 would therefore sit on screen for the whole
+ * multi-minute download and read as "finished but stuck", so anything outside
+ * 0..100 is reported as INDETERMINATE and the status line keeps saying
+ * "downloading".
+ */
+export function summarizeProgress(event: SttProgressEvent): SttProgressSummary {
+  const status = event.status ?? '';
+  if (status === 'progress_total' && typeof event.progress === 'number') {
+    const percent = Math.round(event.progress);
+    return {
+      percent: percent < 0 || percent > 100 ? null : percent,
+      file: event.file,
+      decoding: false,
+    };
+  }
+  if (status === 'initiate' || status === 'download' || status === 'progress') {
+    return { percent: null, file: event.file, decoding: false };
+  }
+  // `done` / `ready`: the fetch is over, so the wait left is decoding.
+  return { percent: null, decoding: true };
+}