@earendil-works/pi-voice 0.1.0

package/src/file-transcription.ts

@@ -0,0 +1,212 @@
+import {
+  DEFAULT_MAX_BYTES,
+  DEFAULT_MAX_LINES,
+  formatSize,
+  truncateHead,
+  type ExtensionAPI,
+  type TruncationResult,
+} from "@earendil-works/pi-coding-agent";
+import { mkdtemp, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, join, resolve } from "node:path";
+import { Type } from "typebox";
+import { AsyncLimiter } from "./async-limiter.js";
+import type { TranscribeSettings } from "./settings.js";
+import type { TranscriptionService } from "./transcription-service.js";
+
+const CONTEXT_LINE_LENGTH = 1_000;
+const MAX_FILE_OPERATIONS = 2;
+const MAX_FILE_DECODERS = 1;
+
+type FileTranscriptionDetails = {
+  inputPath: string;
+  modelId: string;
+  seconds: number;
+  truncation?: TruncationResult;
+  fullTranscriptPath?: string;
+};
+
+type FileTranscriptionOptions = {
+  getSettings: () => Promise<TranscribeSettings>;
+  getService: () => Promise<TranscriptionService>;
+};
+
+export type FileTranscriptionController = {
+  shutdown(): Promise<void>;
+};
+
+function normalizeToolPath(path: string): string {
+  return path.startsWith("@") ? path.slice(1) : path;
+}
+
+/** Wrap long model output lines so Pi's line-aware truncation can retain useful text. */
+function wrapLongLines(text: string): string {
+  const output: string[] = [];
+  for (const originalLine of text.split("\n")) {
+    let line = originalLine;
+    while (line.length > CONTEXT_LINE_LENGTH) {
+      let split = line.lastIndexOf(" ", CONTEXT_LINE_LENGTH);
+      if (split <= 0) split = CONTEXT_LINE_LENGTH;
+      output.push(line.slice(0, split));
+      line = line.slice(split).trimStart();
+    }
+    output.push(line);
+  }
+  return output.join("\n");
+}
+
+async function saveFullTranscript(text: string): Promise<string> {
+  const directory = await mkdtemp(join(tmpdir(), "pi-voice-"));
+  const path = join(directory, "transcript.txt");
+  await writeFile(path, `${text}\n`, "utf8");
+  return path;
+}
+
+export function registerFileTranscriptionTool(
+  pi: ExtensionAPI,
+  options: FileTranscriptionOptions,
+): FileTranscriptionController {
+  let shuttingDown = false;
+  const operations = new Set<Promise<unknown>>();
+  const fileOperations = new AsyncLimiter(MAX_FILE_OPERATIONS);
+  const fileDecoders = new AsyncLimiter(MAX_FILE_DECODERS);
+  const shutdownController = new AbortController();
+
+  function track<T>(operation: Promise<T>): Promise<T> {
+    const tracked = operation.finally(() => {
+      operations.delete(tracked);
+    });
+    operations.add(tracked);
+    return tracked;
+  }
+
+  pi.registerTool({
+    name: "transcribe_file",
+    label: "Transcribe File",
+    description: `Transcribe speech from a local audio or video file using Pi Voice's configured local model. Requires the ffmpeg executable on PATH (or PI_VOICE_FFMPEG_PATH). Output is truncated to ${DEFAULT_MAX_LINES} lines or ${formatSize(DEFAULT_MAX_BYTES)}; a complete transcript is saved to a temporary file when needed.`,
+    promptSnippet: "Transcribe speech from local audio or video files with a local model",
+    promptGuidelines: [
+      "Use transcribe_file when speech in a local audio or video file needs to be read, analyzed, or transcribed.",
+      "transcribe_file automatically queues model work, with interactive dictation taking priority over queued files.",
+      "If transcribe_file reports that FFmpeg is unavailable, explain the installation guidance and ask the user before running a system package-manager command.",
+    ],
+    parameters: Type.Object({
+      path: Type.String({
+        description: "Local media file path, absolute or relative to the current working directory",
+      }),
+    }),
+
+    async execute(_toolCallId, params, signal, onUpdate, ctx) {
+      if (shuttingDown) throw new Error("Pi Voice is shutting down");
+      const operationSignal = signal
+        ? AbortSignal.any([signal, shutdownController.signal])
+        : shutdownController.signal;
+
+      return track(
+        (async () => {
+          operationSignal.throwIfAborted();
+          const input = normalizeToolPath(params.path.trim());
+          if (!input) throw new Error("A media file path is required");
+          const inputPath = resolve(ctx.cwd, input);
+          const inputStat = await stat(inputPath).catch((error: NodeJS.ErrnoException) => {
+            if (error.code === "ENOENT") throw new Error(`Media file not found: ${inputPath}`);
+            throw error;
+          });
+          if (!inputStat.isFile()) throw new Error(`Media path is not a regular file: ${inputPath}`);
+          operationSignal.throwIfAborted();
+
+          const configured = await options.getSettings();
+          const service = await options.getService();
+          if (fileOperations.saturated) {
+            onUpdate?.({
+              content: [{ type: "text", text: "Waiting for file transcription capacity…" }],
+              details: { inputPath, modelId: configured.model.id, seconds: 0 },
+            });
+          }
+
+          return fileOperations.run(async () => {
+            if (fileDecoders.saturated) {
+              onUpdate?.({
+                content: [{ type: "text", text: `Waiting to decode ${basename(inputPath)}…` }],
+                details: { inputPath, modelId: configured.model.id, seconds: 0 },
+              });
+            }
+            const audio = await fileDecoders.run(async () => {
+              onUpdate?.({
+                content: [{ type: "text", text: `Decoding ${basename(inputPath)} with FFmpeg…` }],
+                details: { inputPath, modelId: configured.model.id, seconds: 0 },
+              });
+              const { decodeFileAudio } = await import("./file-audio.js");
+              return decodeFileAudio(inputPath, operationSignal);
+            }, operationSignal);
+
+            onUpdate?.({
+              content: [
+                {
+                  type: "text",
+                  text: `Queued ${audio.seconds.toFixed(1)}s from ${basename(inputPath)} for local transcription…`,
+                },
+              ],
+              details: {
+                inputPath,
+                modelId: configured.model.id,
+                seconds: audio.seconds,
+              },
+            });
+            const transcript = await service.transcribeFile(
+              configured,
+              audio.pcm,
+              operationSignal,
+            );
+            const details: FileTranscriptionDetails = {
+              inputPath,
+              modelId: configured.model.id,
+              seconds: audio.seconds,
+            };
+
+            if (!transcript) {
+              return {
+                content: [
+                  {
+                    type: "text" as const,
+                    text: `No speech detected in ${audio.seconds.toFixed(1)}s of audio from ${inputPath}`,
+                  },
+                ],
+                details,
+              };
+            }
+
+            const contextTranscript =
+              Buffer.byteLength(transcript, "utf8") > DEFAULT_MAX_BYTES
+                ? wrapLongLines(transcript)
+                : transcript;
+            const truncation = truncateHead(contextTranscript, {
+              maxLines: DEFAULT_MAX_LINES,
+              maxBytes: DEFAULT_MAX_BYTES,
+            });
+            let resultText = truncation.content;
+            if (truncation.truncated) {
+              const fullTranscriptPath = await saveFullTranscript(transcript);
+              details.truncation = truncation;
+              details.fullTranscriptPath = fullTranscriptPath;
+              resultText += `\n\n[Transcript truncated: showing ${truncation.outputLines} of ${truncation.totalLines} lines (${formatSize(truncation.outputBytes)} of ${formatSize(truncation.totalBytes)}). Full transcript saved to: ${fullTranscriptPath}]`;
+            }
+
+            return {
+              content: [{ type: "text" as const, text: resultText }],
+              details,
+            };
+          }, operationSignal);
+        })(),
+      );
+    },
+  });
+
+  return {
+    async shutdown() {
+      shuttingDown = true;
+      shutdownController.abort(new Error("Pi Voice is shutting down"));
+      await Promise.allSettled([...operations]);
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,114 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { existsSync } from "node:fs";
+import { registerFileTranscriptionTool } from "./file-transcription.js";
+import {
+  claimLegacyGitNotice,
+  findLegacyGitInstall,
+  legacyGitMigrationMessage,
+} from "./install-migration.js";
+import type { PiVoiceRuntime } from "./runtime.js";
+import { displayShortcut, STATUS_WIDGET_KEY } from "./shortcut-core.js";
+import { legacySettingsPath, settingsPath } from "./settings-path.js";
+import { readShortcutForRegistration } from "./startup-shortcut.js";
+
+// Pi awaits extension module evaluation before continuing startup. Keep this
+// entry point registration-only and load feature implementations on first use.
+export default function piVoice(pi: ExtensionAPI): void {
+  const registeredShortcut = readShortcutForRegistration();
+  let runtimePromise: Promise<PiVoiceRuntime> | undefined;
+  let shuttingDown = false;
+
+  function loadRuntime(): Promise<PiVoiceRuntime> {
+    if (shuttingDown) return Promise.reject(new Error("Pi Voice is shutting down"));
+    if (runtimePromise) return runtimePromise;
+
+    const loading = import("./runtime.js").then(({ createPiVoiceRuntime }) =>
+      createPiVoiceRuntime(pi, registeredShortcut),
+    );
+    runtimePromise = loading;
+    void loading.catch(() => {
+      if (runtimePromise === loading) runtimePromise = undefined;
+    });
+    return loading;
+  }
+
+  pi.on("session_start", async (_event, ctx) => {
+    let showedMigrationNotice = false;
+    if (ctx.mode === "tui") {
+      const legacyInstall = findLegacyGitInstall(pi.getCommands());
+      if (legacyInstall && await claimLegacyGitNotice()) {
+        ctx.ui.notify(legacyGitMigrationMessage(legacyInstall), "warning");
+        showedMigrationNotice = true;
+      }
+    }
+
+    if (
+      !showedMigrationNotice &&
+      !existsSync(settingsPath()) &&
+      !existsSync(legacySettingsPath())
+    ) {
+      ctx.ui.notify(
+        `Pi Voice installed · press ${displayShortcut(registeredShortcut)} or run /voice-settings to set up`,
+        "info",
+      );
+    }
+  });
+
+  const fileTranscription = registerFileTranscriptionTool(pi, {
+    getSettings: async () => (await loadRuntime()).requireConfiguredSettingsForTool(),
+    getService: async () => (await loadRuntime()).service,
+  });
+
+  pi.registerShortcut(
+    registeredShortcut as Parameters<ExtensionAPI["registerShortcut"]>[0],
+    {
+      description: "Toggle microphone transcription",
+      handler: async (ctx) => {
+        // The first press pays deferred module loading before the runtime can
+        // show anything; paint feedback synchronously. Later presses reach the
+        // memoized runtime in a microtask and it paints its own status.
+        if (!runtimePromise && ctx.hasUI) {
+          ctx.ui.setWidget(STATUS_WIDGET_KEY, [
+            ctx.ui.theme.fg("muted", "Starting microphone…"),
+          ]);
+        }
+        try {
+          await (await loadRuntime()).toggleCapture(ctx);
+        } catch (error) {
+          if (ctx.hasUI) ctx.ui.setWidget(STATUS_WIDGET_KEY, undefined);
+          throw error;
+        }
+      },
+    },
+  );
+
+  const openSettings = async (
+    _args: string,
+    ctx: ExtensionCommandContext,
+  ): Promise<void> => (await loadRuntime()).showSettings(ctx);
+
+  pi.registerCommand("voice-settings", {
+    description: "Open Pi Voice settings",
+    handler: openSettings,
+  });
+  pi.registerCommand("transcribe", {
+    description: "Open Pi Voice settings (alias for /voice-settings)",
+    handler: openSettings,
+  });
+
+  if (process.env.PI_VOICE_DEBUG === "1") {
+    pi.registerCommand("voice-onboarding", {
+      description: "Replay Pi Voice onboarding (debug)",
+      handler: async (_args, ctx) => (await loadRuntime()).replayOnboarding(ctx),
+    });
+  }
+
+  pi.on("session_shutdown", async (_event, ctx) => {
+    shuttingDown = true;
+    await fileTranscription.shutdown().catch(() => undefined);
+    const loading = runtimePromise;
+    if (!loading) return;
+    const runtime = await loading.catch(() => undefined);
+    await runtime?.shutdown(ctx).catch(() => undefined);
+  });
+}

package/src/install-migration.ts

@@ -0,0 +1,47 @@
+import type { SlashCommandInfo, SourceInfo } from "@earendil-works/pi-coding-agent";
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+const NOTICE_MARKER_FILENAME = ".pi-voice-legacy-git-notice-v1";
+const LEGACY_GIT_REPOSITORY =
+  /github\.com(?::|\/)earendil-works\/pi-transcribe(?:\.git)?(?:@.*)?\/?$/i;
+
+/** Find a loaded package that still uses the pre-rename Git repository source. */
+export function findLegacyGitInstall(
+  commands: readonly SlashCommandInfo[],
+): SourceInfo | undefined {
+  return commands.find(
+    (command) =>
+      command.source === "extension" &&
+      command.sourceInfo.origin === "package" &&
+      LEGACY_GIT_REPOSITORY.test(command.sourceInfo.source),
+  )?.sourceInfo;
+}
+
+/** Atomically claim the one-time notice across concurrently running Pi processes. */
+export async function claimLegacyGitNotice(): Promise<boolean> {
+  try {
+    await writeFile(join(getAgentDir(), NOTICE_MARKER_FILENAME), "shown\n", {
+      encoding: "utf8",
+      flag: "wx",
+      mode: 0o600,
+    });
+    return true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "EEXIST") return false;
+    // A read-only config directory should not prevent the user from seeing the
+    // migration guidance, even though it means the notice may appear again.
+    return true;
+  }
+}
+
+export function legacyGitMigrationMessage(sourceInfo: SourceInfo): string {
+  const local = sourceInfo.scope === "project" ? " -l" : "";
+  return [
+    "Pi Voice is still installed from the old pi-transcribe Git repository.",
+    "For stable npm updates, replace it with the renamed package:",
+    `pi remove${local} ${sourceInfo.source}`,
+    `pi install${local} npm:@earendil-works/pi-voice`,
+  ].join("\n");
+}

package/src/keybindings.ts

@@ -0,0 +1,118 @@
+import { rawKeyHint } from "@earendil-works/pi-coding-agent";
+import {
+  decodeKittyPrintable,
+  KeybindingsManager,
+  matchesKey,
+  type Keybinding,
+  type KeybindingDefinitions,
+  type KeybindingsConfig,
+  type KeyId,
+} from "@earendil-works/pi-tui";
+
+/**
+ * Every key Pi Voice binds itself, in pi's definition shape. Users
+ * override these with the same ids in pi's keybindings.json; pi keeps entries
+ * it does not recognise and hands them back through `getUserBindings()`.
+ *
+ * Navigation, confirm, and cancel come from pi's `tui.*` ids. Tab is ours: it
+ * continues the language step and browses from Your models. The model pickers
+ * in between swallow the Continue key so the setup sequence never reads Tab as
+ * "go back".
+ */
+export const VOICE_KEYBINDINGS = {
+  "voice.languages.toggle": { defaultKeys: "space", description: "Toggle the highlighted language" },
+  "voice.languages.continue": { defaultKeys: "tab", description: "Continue with the selected languages" },
+  "voice.languages.change": { defaultKeys: "ctrl+l", description: "Change spoken languages" },
+  "voice.recommendations.browseAll": { defaultKeys: "o", description: "Browse all models" },
+  "voice.models.ratingsHelp": { defaultKeys: "?", description: "Open the rating guide" },
+  "voice.ratingsHelp.close": { defaultKeys: "q", description: "Close the rating guide" },
+  "voice.scroll.top": { defaultKeys: "home", description: "Scroll to the top" },
+  "voice.scroll.bottom": { defaultKeys: "end", description: "Scroll to the bottom" },
+  "voice.tryIt.shortcut": { defaultKeys: "s", description: "Change the dictation shortcut" },
+  "voice.tryIt.microphone": { defaultKeys: "m", description: "Change the microphone" },
+  "voice.tryIt.model": { defaultKeys: "c", description: "Change the model" },
+  "voice.shortcut.useDefault": { defaultKeys: "d", description: "Use the default shortcut" },
+  "voice.dictation.cancel": { defaultKeys: "escape", description: "Cancel recording or transcription" },
+} as const satisfies KeybindingDefinitions;
+
+export type VoiceKeybinding = keyof typeof VOICE_KEYBINDINGS;
+/** A pi `tui.*` id or one of ours; callers never need to know which. */
+export type KeyAction = Keybinding | VoiceKeybinding;
+
+export function isVoiceKeybinding(id: string): id is VoiceKeybinding {
+  return Object.hasOwn(VOICE_KEYBINDINGS, id);
+}
+
+// Our ids are not declaration-merged into pi's `Keybindings`, so pi's manager
+// would silently accept them and never match. Route by table membership instead.
+const asTuiId = (id: VoiceKeybinding): Keybinding => id as unknown as Keybinding;
+
+/**
+ * Before the Pi Voice rename our ids were `transcribe.*`. A user binding under
+ * the old id still applies unless the matching `voice.*` id is also set.
+ */
+function withLegacyBindings(user: KeybindingsConfig): KeybindingsConfig {
+  const bindings = { ...user };
+  for (const id of Object.keys(VOICE_KEYBINDINGS)) {
+    const legacy = user[id.replace(/^voice\./, "transcribe.")];
+    if (bindings[id] === undefined && legacy !== undefined) bindings[id] = legacy;
+  }
+  return bindings;
+}
+
+function matchesLocalKey(data: string, key: KeyId): boolean {
+  if (matchesKey(data, key)) return true;
+  // Single printable keys also accept the shifted or caps-lock form and Kitty's
+  // CSI-u report of the typed character, such as `?` arriving as shift+/.
+  if (key.length !== 1) return false;
+  const typed = data.length === 1 ? data : decodeKittyPrintable(data);
+  return typed?.toLowerCase() === key;
+}
+
+/** The user's dictation shortcut is a runtime setting, not a table entry. */
+export function matchesShortcut(data: string, shortcut: string): boolean {
+  return matchesKey(data, shortcut as KeyId);
+}
+
+/**
+ * One matcher and one hint formatter over pi's manager and our table.
+ * Built per pane from the manager pi injects, so the user's bindings for both
+ * apply. Construct it fresh rather than caching: pi's /reload swaps the user
+ * bindings on its manager and the local copy is a snapshot.
+ */
+export class VoiceKeys {
+  private readonly local: KeybindingsManager;
+
+  constructor(readonly host: KeybindingsManager) {
+    this.local = new KeybindingsManager(VOICE_KEYBINDINGS, withLegacyBindings(host.getUserBindings()));
+  }
+
+  matches(data: string, id: KeyAction): boolean {
+    if (!isVoiceKeybinding(id)) return this.host.matches(data, id);
+    return this.local.getKeys(asTuiId(id)).some((key) => matchesLocalKey(data, key));
+  }
+
+  keys(id: KeyAction): KeyId[] {
+    return isVoiceKeybinding(id) ? this.local.getKeys(asTuiId(id)) : this.host.getKeys(id);
+  }
+
+  keyText(id: KeyAction | readonly KeyAction[]): string {
+    const ids = Array.isArray(id) ? (id as readonly KeyAction[]) : [id as KeyAction];
+    return ids.flatMap((each) => this.keys(each)).join("/");
+  }
+
+  hint(id: KeyAction | readonly KeyAction[], description: string): string {
+    return rawKeyHint(this.keyText(id), description);
+  }
+
+  navLabel(): string {
+    const up = this.keys("tui.select.up");
+    const down = this.keys("tui.select.down");
+    const arrows = up.includes("up") && down.includes("down");
+    return arrows ? "↑↓" : `${up.join("/")}/${down.join("/")}`;
+  }
+
+  navHint(description: string): string {
+    return rawKeyHint(this.navLabel(), description);
+  }
+}

package/src/languages.ts

@@ -0,0 +1,22 @@
+/** A base code, without changing the identity or the model's exact code. */
+export function canonicalLanguage(language: string): string {
+  return language.trim().toLowerCase().split("-", 1)[0] ?? "";
+}
+
+// Model cards and benchmarks use different ISO codes for these languages.
+// This identity is for matching, never a code to send directly to a backend.
+const LANGUAGE_ALIASES: Readonly<Record<string, string>> = { tl: "fil", no: "nb" };
+
+export function languageIdentity(language: string): string {
+  const base = canonicalLanguage(language);
+  return LANGUAGE_ALIASES[base] ?? base;
+}
+
+/** Return a model's exact code, preserving an explicitly chosen regional variant. */
+export function resolveModelLanguage(
+  model: { readonly languages: readonly string[] },
+  language: string,
+): string | undefined {
+  const exact = model.languages.find((code) => code.toLowerCase() === language.trim().toLowerCase());
+  return exact ?? model.languages.find((code) => languageIdentity(code) === languageIdentity(language));
+}

package/src/microphone-picker.ts

@@ -0,0 +1,99 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { getAvailableMicrophones, testMicrophonePermission } from "./audio.js";
+import type { MicrophoneSetting } from "./settings.js";
+import { SingleSelectPicker, type SingleSelectChoice } from "./ui-components.js";
+
+export type MicrophonePermission = Awaited<ReturnType<typeof testMicrophonePermission>>;
+
+export function microphoneSummary(microphone: MicrophoneSetting): string {
+  if (microphone.type === "system-default") return "System default";
+  const duplicate = microphone.occurrence > 0 ? ` · device ${microphone.occurrence + 1}` : "";
+  return `${microphone.name}${duplicate}`;
+}
+
+export function microphonesEqual(left: MicrophoneSetting, right: MicrophoneSetting): boolean {
+  return (
+    left.type === right.type &&
+    (left.type === "system-default" ||
+      (right.type === "device" &&
+        left.name === right.name &&
+        left.occurrence === right.occurrence))
+  );
+}
+
+function microphoneChoices(
+  devices: readonly string[],
+  current: MicrophoneSetting,
+): {
+  choices: SingleSelectChoice<string>[];
+  currentValue: string;
+  byValue: Map<string, MicrophoneSetting>;
+} {
+  const totals = new Map<string, number>();
+  for (const name of devices) totals.set(name, (totals.get(name) ?? 0) + 1);
+  const seen = new Map<string, number>();
+  const byValue = new Map<string, MicrophoneSetting>();
+  byValue.set("system-default", { type: "system-default" });
+  const choices: SingleSelectChoice<string>[] = [
+    {
+      value: "system-default",
+      label: "System default",
+      description: "Follow the input device selected by the operating system",
+    },
+  ];
+  let currentValue = "system-default";
+  for (const [index, name] of devices.entries()) {
+    const occurrence = seen.get(name) ?? 0;
+    seen.set(name, occurrence + 1);
+    const microphone: MicrophoneSetting = { type: "device", name, occurrence };
+    const value = `device-${index}`;
+    const label = (totals.get(name) ?? 0) > 1 ? `${name} · device ${occurrence + 1}` : name;
+    choices.push({ value, label });
+    byValue.set(value, microphone);
+    if (microphonesEqual(current, microphone)) currentValue = value;
+  }
+  return { choices, currentValue, byValue };
+}
+
+export function microphonePermissionSummary(result: MicrophonePermission): string {
+  if (result.status === "granted") return "Microphone: ✓ Access granted";
+  if (result.status === "denied") return "Microphone: ✗ Access denied";
+  if (result.status === "not-determined") {
+    return "Microphone: ⚠ Not yet requested — first recording will prompt for access";
+  }
+  return `Microphone: ⚠ ${result.message}`;
+}
+
+export async function chooseMicrophone(
+  ctx: ExtensionContext,
+  current: MicrophoneSetting,
+  permission: MicrophonePermission,
+): Promise<MicrophoneSetting | undefined> {
+  let devices: string[] = [];
+  try {
+    devices = getAvailableMicrophones();
+  } catch (error) {
+    ctx.ui.notify(
+      `Could not list microphones: ${error instanceof Error ? error.message : String(error)}`,
+      "error",
+    );
+  }
+  const { choices, currentValue, byValue } = microphoneChoices(devices, current);
+  const selected = await ctx.ui.custom<string | undefined>((tui, theme, keybindings, done) =>
+    new SingleSelectPicker(
+      tui,
+      theme,
+      keybindings,
+      choices,
+      currentValue,
+      {
+        title: "Choose microphone input",
+        subtitle: microphonePermissionSummary(permission),
+        searchable: choices.length > 8,
+        cancelLabel: "back",
+      },
+      done,
+    ),
+  );
+  return selected ? byValue.get(selected) : undefined;
+}

package/src/model-activation.ts

@@ -0,0 +1,74 @@
+import type { CatalogModel } from "./catalog.js";
+import { downloadCatalogModel, findCachedCatalogModel, type CachedCatalogModel } from "./models.js";
+import { writeSettings, type TranscribeSettings } from "./settings.js";
+
+export type CatalogModelActivation = (
+  model: CatalogModel,
+  options: {
+    cached: CachedCatalogModel | undefined;
+    signal: AbortSignal;
+    onProgress: (progress: { downloaded: number; total: number }) => void;
+  },
+) => Promise<{ path: string }>;
+
+/**
+ * The download-then-save pipeline behind the model picker, shared by
+ * onboarding and the settings menu. Back-to-back selections can outrun their
+ * settings writes; commits run in selection order, so the file always ends on
+ * the user's last choice.
+ */
+export function createModelActivation(options: {
+  buildSettings: (model: CatalogModel, path: string) => TranscribeSettings;
+  onCommitted: (settings: TranscribeSettings) => void;
+}): {
+  activate: CatalogModelActivation;
+  /** Resolves once every commit enqueued so far has landed (or failed). */
+  waitForCommits: () => Promise<void>;
+} {
+  let commitQueue: Promise<void> = Promise.resolve();
+
+  const activate: CatalogModelActivation = async (
+    model,
+    { cached, signal, onProgress },
+  ) => {
+    let path: string;
+    if (cached) {
+      // The picker listed the cache when it opened; re-check so settings
+      // never point at a file that has since been evicted. Integrity is
+      // covered by the download-time hash and the size check here.
+      const stillCached = findCachedCatalogModel(model);
+      if (!stillCached) {
+        throw new Error(
+          "the downloaded file is missing; select the model again to re-download it",
+        );
+      }
+      path = stillCached.path;
+    } else {
+      path = await downloadCatalogModel(model, { signal, onProgress });
+    }
+
+    const commit = commitQueue.then(async () => {
+      // Skip the write when this selection was superseded or its download
+      // was cancelled while the commit sat in the queue.
+      signal.throwIfAborted();
+      let settings: TranscribeSettings;
+      try {
+        settings = options.buildSettings(model, path);
+        await writeSettings(settings);
+      } catch (error) {
+        throw new Error(
+          `Could not save settings: ${error instanceof Error ? error.message : String(error)}`,
+        );
+      }
+      options.onCommitted(settings);
+    });
+    commitQueue = commit.then(
+      () => undefined,
+      () => undefined,
+    );
+    await commit;
+    return { path };
+  };
+
+  return { activate, waitForCommits: () => commitQueue };
+}