@agent-native/toolkit 0.0.0-beta-20260819143124

package/src/composer/useVoiceDictation.ts

@@ -0,0 +1,1256 @@
+/**
+ * Voice dictation hook for the agent composer.
+ *
+ * Wires voice providers behind a single state machine:
+ *   - "auto" / "openai" / "builder" / "builder-gemini" / "gemini" / "groq"
+ *     — MediaRecorder → POST /_agent-native/transcribe-voice
+ *   - "google-realtime"
+ *     — MediaRecorder chunks → POST /_agent-native/transcribe-stream/session
+ *       → managed WebSocket → Google Speech-to-Text streaming
+ *   - "browser" — Web Speech API (low quality, offline capable)
+ *
+ * Provider preference lives in application_state under
+ * `voice-transcription-prefs` (`{ transcriptionMode, provider, instructions }`).
+ * The composer reads it on every start so settings changes take effect
+ * immediately without unmounting the composer.
+ *
+ * The hook exposes amplitude (0..1) and duration (ms) so the composer can
+ * render the Lovable-style live waveform + MM:SS timer.
+ */
+
+import { useCallback, useEffect, useRef, useState } from "react";
+
+import {
+  applyVoiceContextReplacements,
+  type VoiceContextPack,
+  useComposerRuntimeAdapters,
+} from "./runtime-adapters.js";
+
+export type VoiceProvider =
+  | "auto"
+  | "openai"
+  | "browser"
+  | "google-realtime"
+  | "builder-gemini"
+  | "builder"
+  | "gemini"
+  | "groq";
+
+export type TranscriptionMode = "mac-native" | "google-realtime" | "batch";
+
+export interface VoicePrefs {
+  provider: VoiceProvider;
+  transcriptionMode?: TranscriptionMode;
+  instructions?: string;
+  cleanupEnabled?: boolean;
+}
+
+export interface VoiceCleanupPrefs {
+  enabled?: boolean;
+}
+
+type VoiceContextPackSource =
+  | VoiceContextPack
+  | (() => VoiceContextPack | undefined | Promise<VoiceContextPack | undefined>)
+  | undefined;
+
+const PREFS_KEY = "voice-transcription-prefs";
+const CLEANUP_PREFS_KEY = "voice-cleanup-prefs";
+const PREFS_URL = `/_agent-native/application-state/${PREFS_KEY}`;
+const CLEANUP_PREFS_URL = `/_agent-native/application-state/${CLEANUP_PREFS_KEY}`;
+const TRANSCRIBE_URL = "/_agent-native/transcribe-voice";
+const GOOGLE_REALTIME_SESSION_URL = "/_agent-native/transcribe-stream/session";
+const GOOGLE_REALTIME_WS_PROTOCOL = "google-realtime.v1";
+function isVoiceProvider(value: unknown): value is VoiceProvider {
+  return (
+    value === "auto" ||
+    value === "openai" ||
+    value === "browser" ||
+    value === "google-realtime" ||
+    value === "builder-gemini" ||
+    value === "builder" ||
+    value === "gemini" ||
+    value === "groq"
+  );
+}
+
+function isTranscriptionMode(value: unknown): value is TranscriptionMode {
+  return (
+    value === "mac-native" || value === "google-realtime" || value === "batch"
+  );
+}
+
+async function defaultProvider(): Promise<VoiceProvider> {
+  return "auto";
+}
+
+function normalizeProviderForMode(
+  mode: TranscriptionMode | undefined,
+  provider: VoiceProvider | null,
+): VoiceProvider | null {
+  if (mode === "mac-native") return "browser";
+  if (mode === "google-realtime") return "google-realtime";
+  if (mode === "batch") {
+    if (!provider || provider === "browser") return "auto";
+    return provider === "builder" ? "builder-gemini" : provider;
+  }
+  if (!provider) return null;
+  return provider === "builder" ? "builder-gemini" : provider;
+}
+
+export type VoiceState =
+  | "idle"
+  | "starting"
+  | "recording"
+  | "transcribing"
+  | "error";
+
+export interface UseVoiceDictationOptions {
+  onTranscript: (text: string) => void;
+  onError?: (message: string) => void;
+  /** Called with (accumulatedFinalText, currentInterimText) as speech is recognized in real time. */
+  onLiveUpdate?: (finalText: string, interimText: string) => void;
+  contextPack?: VoiceContextPackSource;
+}
+
+export interface VoiceDictationApi {
+  state: VoiceState;
+  amplitude: number;
+  durationMs: number;
+  errorMessage: string | null;
+  provider: VoiceProvider;
+  supported: boolean;
+  start: () => Promise<void>;
+  stop: () => void;
+  cancel: () => void;
+  dismissError: () => void;
+}
+
+async function readVoicePrefs(
+  resolvePath: (path: string) => string,
+): Promise<VoicePrefs> {
+  const cleanupPrefs = await readVoiceCleanupPrefs(resolvePath);
+  try {
+    const res = await fetch(resolvePath(PREFS_URL));
+    if (!res.ok) {
+      return {
+        provider: await defaultProvider(),
+        cleanupEnabled: cleanupPrefs.enabled,
+      };
+    }
+    const body = (await res.json()) as
+      | VoicePrefs
+      | { value?: VoicePrefs }
+      | null;
+    const value =
+      (body as { value?: VoicePrefs } | null)?.value ??
+      (body as VoicePrefs | null);
+    const mode = isTranscriptionMode(value?.transcriptionMode)
+      ? value.transcriptionMode
+      : undefined;
+    const p =
+      (body as VoicePrefs | null)?.provider ??
+      (body as { value?: VoicePrefs } | null)?.value?.provider;
+    const instructions =
+      (body as VoicePrefs | null)?.instructions ??
+      (body as { value?: VoicePrefs } | null)?.value?.instructions;
+    const provider = normalizeProviderForMode(
+      mode,
+      isVoiceProvider(p) ? p : null,
+    );
+    if (provider) {
+      return {
+        transcriptionMode: mode,
+        provider,
+        cleanupEnabled: cleanupPrefs.enabled,
+        instructions:
+          typeof instructions === "string" ? instructions.trim() : undefined,
+      };
+    }
+  } catch {
+    /* fall through */
+  }
+  return {
+    provider: await defaultProvider(),
+    cleanupEnabled: cleanupPrefs.enabled,
+  };
+}
+
+async function readVoiceCleanupPrefs(
+  resolvePath: (path: string) => string,
+): Promise<VoiceCleanupPrefs> {
+  try {
+    const res = await fetch(resolvePath(CLEANUP_PREFS_URL));
+    if (!res.ok) return {};
+    const body = (await res.json()) as
+      | VoiceCleanupPrefs
+      | { value?: VoiceCleanupPrefs }
+      | null;
+    const value =
+      (body as { value?: VoiceCleanupPrefs } | null)?.value ??
+      (body as VoiceCleanupPrefs | null);
+    return { enabled: value?.enabled === true };
+  } catch {
+    return {};
+  }
+}
+
+function getSpeechRecognitionCtor(): any {
+  if (typeof window === "undefined") return null;
+  return (
+    (window as any).SpeechRecognition ||
+    (window as any).webkitSpeechRecognition ||
+    null
+  );
+}
+
+function pickMimeType(): string {
+  if (typeof MediaRecorder === "undefined") return "audio/webm";
+  const candidates = [
+    "audio/webm;codecs=opus",
+    "audio/webm",
+    "audio/mp4",
+    "audio/ogg;codecs=opus",
+  ];
+  for (const mime of candidates) {
+    try {
+      if (MediaRecorder.isTypeSupported(mime)) return mime;
+    } catch {
+      /* ignore */
+    }
+  }
+  return "audio/webm";
+}
+
+async function resolveVoiceContextPack(
+  source: VoiceContextPackSource,
+): Promise<VoiceContextPack | undefined> {
+  try {
+    const value = typeof source === "function" ? await source() : source;
+    return value && typeof value === "object" ? value : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function appendVoiceContext(
+  form: FormData,
+  contextPack: VoiceContextPack | undefined,
+): void {
+  if (!contextPack) return;
+  try {
+    form.append("voiceContext", JSON.stringify(contextPack));
+  } catch {
+    /* best effort */
+  }
+}
+
+export function providerForTextCleanup(provider: VoiceProvider): VoiceProvider {
+  return provider === "google-realtime" ? "auto" : provider;
+}
+
+async function cleanupRecognizedText({
+  text,
+  provider,
+  instructions,
+  contextPack,
+  resolvePath,
+  replaceContext,
+}: {
+  text: string;
+  provider: VoiceProvider;
+  instructions?: string;
+  contextPack?: VoiceContextPack;
+  resolvePath: (path: string) => string;
+  replaceContext: (
+    text: string,
+    context: VoiceContextPack | undefined,
+  ) => string;
+}): Promise<string> {
+  if (provider === "browser") {
+    return replaceContext(text, contextPack);
+  }
+
+  const form = new FormData();
+  form.append("text", text);
+  form.append("provider", providerForTextCleanup(provider));
+  if (instructions?.trim()) {
+    form.append("instructions", instructions.trim());
+  }
+  appendVoiceContext(form, contextPack);
+
+  const res = await fetch(resolvePath(TRANSCRIBE_URL), {
+    method: "POST",
+    body: form,
+  });
+  if (!res.ok) {
+    const body = await res
+      .json()
+      .catch(() => ({ error: `HTTP ${res.status}` }));
+    throw new Error(body.error || `Transcript cleanup failed (${res.status})`);
+  }
+  const data = (await res.json()) as { text?: string };
+  return (data.text ?? "").trim() || text;
+}
+
+type BrowserDocumentPolicy = {
+  allowsFeature: (feature: string) => boolean;
+};
+
+function microphoneBlockedByPermissionsPolicy(): boolean {
+  if (typeof document === "undefined") return false;
+  const doc = document as Document & {
+    permissionsPolicy?: BrowserDocumentPolicy;
+    featurePolicy?: BrowserDocumentPolicy;
+  };
+  const policy = doc.permissionsPolicy ?? doc.featurePolicy ?? null;
+  if (!policy?.allowsFeature) return false;
+  try {
+    return !policy.allowsFeature("microphone");
+  } catch {
+    return false;
+  }
+}
+
+export function voiceDictationStartErrorMessage(error: unknown): string {
+  const name =
+    typeof (error as { name?: unknown } | null)?.name === "string"
+      ? (error as { name: string }).name
+      : "";
+  const message =
+    typeof (error as { message?: unknown } | null)?.message === "string"
+      ? (error as { message: string }).message
+      : "";
+
+  if (
+    microphoneBlockedByPermissionsPolicy() ||
+    /permissions[- ]policy|feature policy/i.test(message)
+  ) {
+    return "This app is blocking microphone access through its browser permissions policy. Reload the app, or open it directly in a browser tab.";
+  }
+
+  if (
+    name === "NotAllowedError" ||
+    name === "SecurityError" ||
+    /permission|denied|not allowed/i.test(message)
+  ) {
+    return "Microphone access is blocked. Click the site controls icon in the address bar, set Microphone to Allow for this app, then try again.";
+  }
+
+  if (name === "NotFoundError" || name === "DevicesNotFoundError") {
+    return "No microphone was found. Plug one in or choose a different input, then try again.";
+  }
+
+  if (name === "NotReadableError" || name === "TrackStartError") {
+    return "Your microphone is busy in another app. Close the other app or choose a different input, then try again.";
+  }
+
+  return message || "Could not start recording";
+}
+
+/** Retrying these through another provider re-prompts and fails the same way. */
+function isMicPermissionError(error: string | undefined): boolean {
+  return (
+    error === "not-allowed" ||
+    error === "service-not-allowed" ||
+    error === "audio-capture"
+  );
+}
+
+export function voiceDictationSpeechErrorMessage(
+  error: string | undefined,
+): string {
+  if (error === "not-allowed" || error === "service-not-allowed") {
+    return voiceDictationStartErrorMessage({
+      name: "NotAllowedError",
+      message: error,
+    });
+  }
+  if (error === "audio-capture") {
+    return "No microphone was found. Plug one in or choose a different input, then try again.";
+  }
+  if (error === "network") {
+    return "Speech recognition couldn't reach its service. Check your connection, or pick a different source in Settings → Voice Transcription.";
+  }
+  if (error === "aborted" || error === undefined) {
+    return "Dictation stopped before it captured any audio. Another app or tab may be holding the microphone — close it, or pick a different source in Settings → Voice Transcription.";
+  }
+  return `Speech recognition error: ${error}`;
+}
+
+export function useVoiceDictation(
+  options: UseVoiceDictationOptions,
+): VoiceDictationApi {
+  const adapters = useComposerRuntimeAdapters();
+  const resolvePath = adapters.resolvePath!;
+  const replaceContext =
+    adapters.voice!.applyContextReplacements ?? applyVoiceContextReplacements;
+  const { onTranscript, onError, onLiveUpdate, contextPack } = options;
+  const onTranscriptRef = useRef(onTranscript);
+  const onErrorRef = useRef(onError);
+  const onLiveUpdateRef = useRef(onLiveUpdate);
+  const contextPackRef = useRef(contextPack);
+  onTranscriptRef.current = onTranscript;
+  onErrorRef.current = onError;
+  onLiveUpdateRef.current = onLiveUpdate;
+  contextPackRef.current = contextPack;
+
+  const [state, setState] = useState<VoiceState>("idle");
+  const [amplitude, setAmplitude] = useState(0);
+  const [durationMs, setDurationMs] = useState(0);
+  const [errorMessage, setErrorMessage] = useState<string | null>(null);
+  const [provider, setProvider] = useState<VoiceProvider>("auto");
+
+  // Keep refs for teardown / cross-branch access.
+  const mediaStreamRef = useRef<MediaStream | null>(null);
+  const mediaRecorderRef = useRef<MediaRecorder | null>(null);
+  const chunksRef = useRef<Blob[]>([]);
+  const audioContextRef = useRef<AudioContext | null>(null);
+  const analyserRef = useRef<AnalyserNode | null>(null);
+  const rafRef = useRef<number | null>(null);
+  const timerRef = useRef<ReturnType<typeof setInterval> | null>(null);
+  const startedAtRef = useRef<number>(0);
+  const cancelledRef = useRef(false);
+  const speechRef = useRef<any>(null);
+  const speechTranscriptRef = useRef<string>("");
+  const activeProviderRef = useRef<VoiceProvider>("browser");
+  // Parallel live recognition for OpenAI mode (provides instant preview while MediaRecorder captures)
+  const liveSpeechRef = useRef<any>(null);
+  const liveTextRef = useRef<string>("");
+  const realtimeSocketRef = useRef<WebSocket | null>(null);
+  const realtimeFinalRef = useRef<string>("");
+  const realtimeInterimRef = useRef<string>("");
+  const realtimeStopTimeoutRef = useRef<number | null>(null);
+
+  const mediaRecorderSupported =
+    typeof window !== "undefined" &&
+    typeof navigator !== "undefined" &&
+    !!navigator.mediaDevices?.getUserMedia &&
+    typeof (window as any).MediaRecorder !== "undefined";
+  const speechSupported = !!getSpeechRecognitionCtor();
+  const supported = mediaRecorderSupported || speechSupported;
+
+  const teardown = useCallback(() => {
+    if (rafRef.current != null) {
+      cancelAnimationFrame(rafRef.current);
+      rafRef.current = null;
+    }
+    if (timerRef.current != null) {
+      clearInterval(timerRef.current);
+      timerRef.current = null;
+    }
+    if (mediaStreamRef.current) {
+      for (const track of mediaStreamRef.current.getTracks()) {
+        track.stop();
+      }
+      mediaStreamRef.current = null;
+    }
+    if (audioContextRef.current) {
+      audioContextRef.current.close().catch(() => {});
+      audioContextRef.current = null;
+    }
+    if (speechRef.current) {
+      // Stop the Web Speech session before dropping the ref so the browser
+      // releases the mic and stops dispatching onresult events into a stale
+      // closure. abort() is fire-and-forget (no final result); stop() would
+      // deliver remaining partials but we've already cleared state.
+      try {
+        speechRef.current.abort?.();
+      } catch {
+        /* ignore */
+      }
+    }
+    if (liveSpeechRef.current) {
+      try {
+        liveSpeechRef.current.abort?.();
+      } catch {
+        /* ignore */
+      }
+      liveSpeechRef.current = null;
+    }
+    if (realtimeSocketRef.current) {
+      const socket = realtimeSocketRef.current;
+      realtimeSocketRef.current = null;
+      try {
+        socket.close();
+      } catch {
+        /* ignore */
+      }
+    }
+    if (realtimeStopTimeoutRef.current) {
+      clearTimeout(realtimeStopTimeoutRef.current);
+      realtimeStopTimeoutRef.current = null;
+    }
+    analyserRef.current = null;
+    mediaRecorderRef.current = null;
+    chunksRef.current = [];
+    speechRef.current = null;
+    speechTranscriptRef.current = "";
+    liveTextRef.current = "";
+    realtimeFinalRef.current = "";
+    realtimeInterimRef.current = "";
+    setAmplitude(0);
+  }, []);
+
+  useEffect(() => teardown, [teardown]);
+
+  const failWith = useCallback(
+    (message: string) => {
+      setErrorMessage(message);
+      setState("error");
+      onErrorRef.current?.(message);
+      teardown();
+    },
+    [teardown],
+  );
+
+  const getVoiceContextPack = useCallback(
+    () => resolveVoiceContextPack(contextPackRef.current),
+    [],
+  );
+
+  const startMeter = useCallback((stream: MediaStream) => {
+    try {
+      const AudioCtor =
+        typeof window !== "undefined"
+          ? window.AudioContext || (window as any).webkitAudioContext || null
+          : null;
+      if (!AudioCtor) return;
+      const ctx: AudioContext = new AudioCtor();
+      const source = ctx.createMediaStreamSource(stream);
+      const analyser = ctx.createAnalyser();
+      analyser.fftSize = 512;
+      source.connect(analyser);
+      audioContextRef.current = ctx;
+      analyserRef.current = analyser;
+
+      const buffer = new Uint8Array(analyser.frequencyBinCount);
+      const tick = () => {
+        if (!analyserRef.current) return;
+        analyserRef.current.getByteTimeDomainData(buffer);
+        let sumSquares = 0;
+        for (let i = 0; i < buffer.length; i++) {
+          const n = (buffer[i] - 128) / 128;
+          sumSquares += n * n;
+        }
+        const rms = Math.sqrt(sumSquares / buffer.length);
+        setAmplitude(Math.min(1, rms * 2.5));
+        rafRef.current = requestAnimationFrame(tick);
+      };
+      rafRef.current = requestAnimationFrame(tick);
+    } catch {
+      /* analyser is best-effort */
+    }
+  }, []);
+
+  const startTimer = useCallback(() => {
+    startedAtRef.current = Date.now();
+    setDurationMs(0);
+    timerRef.current = setInterval(() => {
+      setDurationMs(Date.now() - startedAtRef.current);
+    }, 100);
+  }, []);
+
+  const startOpenAi = useCallback(
+    async (providerPref: VoiceProvider, instructions?: string) => {
+      const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+      // User may have pressed Escape (cancel) while the permission prompt was
+      // open. If so, stop the stream and bail before we start recording.
+      if (cancelledRef.current) {
+        for (const track of stream.getTracks()) track.stop();
+        cancelledRef.current = false;
+        setState("idle");
+        return;
+      }
+      mediaStreamRef.current = stream;
+      const mimeType = pickMimeType();
+      const recorder = new MediaRecorder(stream, { mimeType });
+      mediaRecorderRef.current = recorder;
+      chunksRef.current = [];
+
+      recorder.ondataavailable = (e) => {
+        if (e.data && e.data.size > 0) chunksRef.current.push(e.data);
+      };
+      recorder.onstop = async () => {
+        const localChunks = chunksRef.current.slice();
+        const localMime = recorder.mimeType || mimeType;
+        const liveSnapshot = liveTextRef.current;
+        teardown();
+        if (cancelledRef.current) {
+          cancelledRef.current = false;
+          setState("idle");
+          return;
+        }
+        if (localChunks.length === 0) {
+          if (liveSnapshot) onTranscriptRef.current?.(liveSnapshot.trim());
+          setState("idle");
+          return;
+        }
+        setState("transcribing");
+        try {
+          const audioBlob = new Blob(localChunks, { type: localMime });
+          const form = new FormData();
+          form.append(
+            "audio",
+            audioBlob,
+            `voice.${localMime.split("/")[1] ?? "webm"}`,
+          );
+          form.append("provider", providerPref);
+          if (instructions?.trim()) {
+            form.append("instructions", instructions.trim());
+          }
+          appendVoiceContext(form, await getVoiceContextPack());
+          const res = await fetch(resolvePath(TRANSCRIBE_URL), {
+            method: "POST",
+            body: form,
+          });
+          if (!res.ok) {
+            const body = await res
+              .json()
+              .catch(() => ({ error: `HTTP ${res.status}` }));
+            throw new Error(
+              body.error || `Transcription failed (${res.status})`,
+            );
+          }
+          if (cancelledRef.current) {
+            cancelledRef.current = false;
+            setState("idle");
+            return;
+          }
+          const data = (await res.json()) as { text?: string };
+          const text = (data.text ?? "").trim();
+          if (text) {
+            onTranscriptRef.current?.(text);
+          } else if (liveSnapshot) {
+            onTranscriptRef.current?.(liveSnapshot.trim());
+          }
+          setState("idle");
+        } catch (err) {
+          if (cancelledRef.current) {
+            cancelledRef.current = false;
+            setState("idle");
+            return;
+          }
+          if (liveSnapshot) {
+            onTranscriptRef.current?.(liveSnapshot.trim());
+            setState("idle");
+          } else {
+            failWith(
+              (err as Error)?.message ??
+                "Transcription failed. Check your voice transcription provider in settings.",
+            );
+          }
+        }
+      };
+
+      startMeter(stream);
+      startTimer();
+      setState("recording");
+      recorder.start();
+
+      // Start parallel Web Speech recognition for live preview text.
+      // This runs alongside MediaRecorder so the user sees words appear
+      // immediately while the server provider processes the full recording later.
+      const SpeechCtor = getSpeechRecognitionCtor();
+      if (SpeechCtor) {
+        const liveSpeech = new SpeechCtor();
+        liveSpeech.continuous = true;
+        liveSpeech.interimResults = true;
+        liveSpeech.lang =
+          (typeof navigator !== "undefined" && navigator.language) || "en-US";
+        liveSpeechRef.current = liveSpeech;
+        liveTextRef.current = "";
+
+        liveSpeech.onresult = (event: any) => {
+          let interim = "";
+          for (let i = event.resultIndex; i < event.results.length; i++) {
+            const result = event.results[i];
+            const text = result[0]?.transcript ?? "";
+            if (result.isFinal) {
+              liveTextRef.current += text;
+            } else {
+              interim += text;
+            }
+          }
+          onLiveUpdateRef.current?.(liveTextRef.current, interim);
+        };
+
+        liveSpeech.onend = () => {
+          if (liveSpeechRef.current === liveSpeech) {
+            try {
+              liveSpeech.start();
+            } catch {
+              /* ignore */
+            }
+          }
+        };
+
+        liveSpeech.onerror = () => {};
+
+        try {
+          liveSpeech.start();
+        } catch {
+          /* best effort — live preview just won't appear */
+        }
+      }
+    },
+    [
+      startMeter,
+      startTimer,
+      teardown,
+      failWith,
+      getVoiceContextPack,
+      resolvePath,
+    ],
+  );
+
+  const startBrowser = useCallback(
+    async (
+      prefs: VoicePrefs,
+      /** Return true to take over when the recognizer never opened the mic.
+       * Brave ships `webkitSpeechRecognition` with no speech backend, so
+       * feature detection alone cannot tell dictation will work. */
+      onUnavailable?: (error: string | undefined) => boolean,
+    ) => {
+      const Ctor = getSpeechRecognitionCtor();
+      if (!Ctor) {
+        throw new Error(
+          "Your browser doesn't support speech recognition. Add an OpenAI API key in settings for Whisper transcription.",
+        );
+      }
+      if (cancelledRef.current) {
+        cancelledRef.current = false;
+        setState("idle");
+        return;
+      }
+
+      const recognition = new Ctor();
+      recognition.continuous = true;
+      recognition.interimResults = true;
+      recognition.lang =
+        (typeof navigator !== "undefined" && navigator.language) || "en-US";
+      speechRef.current = recognition;
+      speechTranscriptRef.current = "";
+
+      let capturing = false;
+      let fatal = false;
+      let lastError: string | undefined;
+
+      // Opening our own capture before the speech service has claimed the
+      // device makes Chrome abort the session outright. Attach the meter only
+      // once recognition is actually listening.
+      recognition.onaudiostart = () => {
+        capturing = true;
+        if (cancelledRef.current) return;
+        void Promise.resolve()
+          .then(() => navigator.mediaDevices?.getUserMedia({ audio: true }))
+          .then((stream) => {
+            if (!stream) return;
+            if (cancelledRef.current || speechRef.current !== recognition) {
+              for (const track of stream.getTracks()) track.stop();
+              return;
+            }
+            mediaStreamRef.current = stream;
+            startMeter(stream);
+          })
+          .catch(() => {
+            /* the meter is decoration; recognition owns the real capture */
+          });
+      };
+
+      recognition.onresult = (event: any) => {
+        capturing = true;
+        let interim = "";
+        for (let i = event.resultIndex; i < event.results.length; i++) {
+          const result = event.results[i];
+          const text = result[0]?.transcript ?? "";
+          if (result.isFinal) {
+            speechTranscriptRef.current += text;
+          } else {
+            interim += text;
+          }
+        }
+        onLiveUpdateRef.current?.(speechTranscriptRef.current, interim);
+      };
+      // `end` always follows `error`, so every outcome is decided there. Acting
+      // here too would either pre-empt the fallback or be overwritten by it.
+      recognition.onerror = (event: any) => {
+        lastError = event?.error;
+        if (event?.error === "no-speech" || event?.error === "aborted") return;
+        fatal = true;
+      };
+      recognition.onend = () => {
+        const text = speechTranscriptRef.current.trim();
+        const wasCancelled = cancelledRef.current;
+        cancelledRef.current = false;
+        teardown();
+        if (wasCancelled) {
+          setState("idle");
+          return;
+        }
+        if (!text) {
+          // A recognizer that failed, or that ended before the mic ever opened,
+          // produced nothing usable — that is not the same as hearing silence.
+          if (fatal || !capturing) {
+            if (onUnavailable?.(lastError)) return;
+            failWith(voiceDictationSpeechErrorMessage(lastError));
+            return;
+          }
+          setState("idle");
+          return;
+        }
+        void (async () => {
+          let finalText = text;
+          if (prefs.cleanupEnabled) {
+            setState("transcribing");
+            try {
+              finalText = await cleanupRecognizedText({
+                text,
+                provider: prefs.provider,
+                instructions: prefs.instructions,
+                contextPack: await getVoiceContextPack(),
+                resolvePath,
+                replaceContext,
+              });
+            } catch {
+              finalText = text;
+            }
+          }
+          if (!cancelledRef.current && finalText) {
+            onTranscriptRef.current?.(finalText);
+          }
+          cancelledRef.current = false;
+          setState("idle");
+        })();
+      };
+
+      startTimer();
+      setState("recording");
+      recognition.start();
+    },
+    [
+      startMeter,
+      startTimer,
+      teardown,
+      failWith,
+      getVoiceContextPack,
+      replaceContext,
+      resolvePath,
+    ],
+  );
+
+  const startGoogleRealtime = useCallback(
+    async (prefs: VoicePrefs) => {
+      const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+      if (cancelledRef.current) {
+        for (const track of stream.getTracks()) track.stop();
+        cancelledRef.current = false;
+        setState("idle");
+        return;
+      }
+
+      const sessionRes = await fetch(resolvePath(GOOGLE_REALTIME_SESSION_URL), {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          language:
+            (typeof navigator !== "undefined" && navigator.language) || "en-US",
+        }),
+      });
+      const sessionBody = (await sessionRes
+        .json()
+        .catch(() => ({ error: `HTTP ${sessionRes.status}` }))) as {
+        websocketUrl?: string;
+        websocketProtocol?: string;
+        sessionToken?: string;
+        error?: string;
+      };
+      if (
+        !sessionRes.ok ||
+        !sessionBody.websocketUrl ||
+        !sessionBody.sessionToken
+      ) {
+        for (const track of stream.getTracks()) track.stop();
+        throw new Error(
+          sessionBody.error ||
+            `Could not start Google realtime transcription (${sessionRes.status})`,
+        );
+      }
+      if (cancelledRef.current) {
+        for (const track of stream.getTracks()) track.stop();
+        cancelledRef.current = false;
+        setState("idle");
+        return;
+      }
+
+      mediaStreamRef.current = stream;
+      const mimeType = pickMimeType();
+      const recorder = new MediaRecorder(stream, { mimeType });
+      mediaRecorderRef.current = recorder;
+      realtimeFinalRef.current = "";
+      realtimeInterimRef.current = "";
+
+      let finalized = false;
+      let recorderStarted = false;
+      const finish = (errorMessage?: string) => {
+        if (finalized) return;
+        finalized = true;
+        void (async () => {
+          const finalText = realtimeFinalRef.current.trim();
+          const interimText = realtimeInterimRef.current.trim();
+          const text = [finalText, interimText]
+            .filter(Boolean)
+            .join(" ")
+            .trim();
+          teardown();
+          if (cancelledRef.current) {
+            cancelledRef.current = false;
+            setState("idle");
+            return;
+          }
+          if (text) {
+            let cleanedText = text;
+            if (prefs.cleanupEnabled) {
+              setState("transcribing");
+              try {
+                cleanedText = await cleanupRecognizedText({
+                  text,
+                  provider: prefs.provider,
+                  instructions: prefs.instructions,
+                  contextPack: await getVoiceContextPack(),
+                  resolvePath,
+                  replaceContext,
+                });
+              } catch {
+                cleanedText = text;
+              }
+            }
+            if (!cancelledRef.current && cleanedText) {
+              onTranscriptRef.current?.(cleanedText);
+            }
+            cancelledRef.current = false;
+            setState("idle");
+            return;
+          }
+          if (errorMessage) {
+            failWith(errorMessage);
+            return;
+          }
+          setState("idle");
+        })();
+      };
+
+      recorder.ondataavailable = async (event) => {
+        if (!event.data || event.data.size === 0) return;
+        const socket = realtimeSocketRef.current;
+        if (!socket || socket.readyState !== WebSocket.OPEN) return;
+        try {
+          socket.send(await event.data.arrayBuffer());
+        } catch (err) {
+          finish((err as Error)?.message ?? "Realtime audio upload failed");
+        }
+      };
+
+      recorder.onstop = () => {
+        const socket = realtimeSocketRef.current;
+        if (!socket || socket.readyState !== WebSocket.OPEN) {
+          finish();
+          return;
+        }
+        setState("transcribing");
+        try {
+          socket.send(JSON.stringify({ type: "stop" }));
+        } catch {
+          finish();
+          return;
+        }
+        realtimeStopTimeoutRef.current = window.setTimeout(() => {
+          const activeSocket = realtimeSocketRef.current;
+          if (activeSocket?.readyState === WebSocket.OPEN) {
+            try {
+              activeSocket.close();
+            } catch {
+              finish();
+            }
+            return;
+          }
+          finish();
+        }, 10000);
+      };
+
+      const socket = new WebSocket(sessionBody.websocketUrl, [
+        sessionBody.websocketProtocol || GOOGLE_REALTIME_WS_PROTOCOL,
+        sessionBody.sessionToken,
+      ]);
+      socket.binaryType = "arraybuffer";
+      realtimeSocketRef.current = socket;
+
+      socket.onmessage = (event) => {
+        if (cancelledRef.current) {
+          finish();
+          return;
+        }
+        const raw =
+          typeof event.data === "string"
+            ? event.data
+            : event.data instanceof Blob
+              ? null
+              : new TextDecoder().decode(event.data);
+        if (!raw) return;
+        let message:
+          | {
+              type?: string;
+              text?: string;
+              error?: string;
+            }
+          | undefined;
+        try {
+          message = JSON.parse(raw);
+        } catch {
+          return;
+        }
+        if (!message?.type) return;
+        if (message.type === "ready") {
+          if (!recorderStarted) {
+            recorderStarted = true;
+            startMeter(stream);
+            startTimer();
+            setState("recording");
+            recorder.start(100);
+          }
+          return;
+        }
+        if (message.type === "partial") {
+          realtimeInterimRef.current = (message.text ?? "").trim();
+          onLiveUpdateRef.current?.(
+            realtimeFinalRef.current,
+            realtimeInterimRef.current,
+          );
+          return;
+        }
+        if (message.type === "final") {
+          const next = (message.text ?? "").trim();
+          if (next) {
+            realtimeFinalRef.current = [realtimeFinalRef.current.trim(), next]
+              .filter(Boolean)
+              .join(" ");
+          }
+          realtimeInterimRef.current = "";
+          onLiveUpdateRef.current?.(realtimeFinalRef.current, "");
+          return;
+        }
+        if (message.type === "error") {
+          finish(message.error || "Google realtime transcription failed");
+          return;
+        }
+        if (message.type === "end") {
+          finish();
+        }
+      };
+
+      socket.onerror = () => {
+        finish("Google realtime transcription connection failed");
+      };
+
+      socket.onclose = () => {
+        finish();
+      };
+
+      socket.onopen = () => {
+        if (cancelledRef.current) {
+          finish();
+          return;
+        }
+        try {
+          socket.send(
+            JSON.stringify({
+              type: "start",
+              language:
+                (typeof navigator !== "undefined" && navigator.language) ||
+                "en-US",
+              interimResults: true,
+              mimeType,
+            }),
+          );
+        } catch (err) {
+          finish((err as Error)?.message ?? "Could not start realtime stream");
+        }
+      };
+    },
+    [
+      startMeter,
+      startTimer,
+      teardown,
+      failWith,
+      getVoiceContextPack,
+      replaceContext,
+      resolvePath,
+    ],
+  );
+
+  const start = useCallback(async () => {
+    if (state === "recording" || state === "starting") return;
+    setErrorMessage(null);
+    setState("starting");
+    cancelledRef.current = false;
+
+    const prefs = await readVoicePrefs(resolvePath);
+    const pref = prefs.provider;
+    setProvider(pref);
+
+    // In "auto" mode, prefer browser-native SpeechRecognition when available.
+    // It requires no server-side API key, streams words incrementally into the
+    // composer, and matches the macros-app record-button experience. Fall back
+    // to the server upload path only when SpeechRecognition isn't supported.
+    // Explicit server providers (builder, gemini, groq, openai) always use the
+    // MediaRecorder → server upload path regardless.
+    const resolvedProvider: VoiceProvider =
+      pref === "auto" && speechSupported
+        ? "browser"
+        : pref === "auto" ||
+            pref === "builder" ||
+            pref === "builder-gemini" ||
+            pref === "gemini" ||
+            pref === "groq"
+          ? "openai"
+          : pref;
+    activeProviderRef.current = resolvedProvider;
+
+    try {
+      if (resolvedProvider === "openai") {
+        if (!mediaRecorderSupported) {
+          throw new Error(
+            "Your browser doesn't support audio recording. Use the browser provider in Settings → Voice Transcription.",
+          );
+        }
+        await startOpenAi(pref, prefs.instructions);
+      } else if (resolvedProvider === "google-realtime") {
+        if (!mediaRecorderSupported) {
+          throw new Error(
+            "Your browser doesn't support audio recording, so Google realtime transcription can't start.",
+          );
+        }
+        await startGoogleRealtime(prefs);
+      } else {
+        // Only "auto" promised a working recognizer of any kind; an explicit
+        // browser preference must surface its own failure instead.
+        await startBrowser(
+          prefs,
+          pref === "auto" && mediaRecorderSupported
+            ? (error) => {
+                if (isMicPermissionError(error)) return false;
+                activeProviderRef.current = "openai";
+                setState("starting");
+                void startOpenAi("auto", prefs.instructions).catch((err) =>
+                  failWith(voiceDictationStartErrorMessage(err)),
+                );
+                return true;
+              }
+            : undefined,
+        );
+      }
+    } catch (err) {
+      if (cancelledRef.current) {
+        cancelledRef.current = false;
+        teardown();
+        setState("idle");
+        return;
+      }
+      failWith(voiceDictationStartErrorMessage(err));
+    }
+  }, [
+    state,
+    speechSupported,
+    mediaRecorderSupported,
+    startOpenAi,
+    startGoogleRealtime,
+    startBrowser,
+    failWith,
+  ]);
+
+  const stop = useCallback(() => {
+    if (state !== "recording") return;
+    cancelledRef.current = false;
+    if (
+      (activeProviderRef.current === "openai" ||
+        activeProviderRef.current === "google-realtime") &&
+      mediaRecorderRef.current
+    ) {
+      try {
+        mediaRecorderRef.current.stop();
+      } catch {
+        teardown();
+        setState("idle");
+      }
+    } else if (speechRef.current) {
+      try {
+        speechRef.current.stop();
+      } catch {
+        teardown();
+        setState("idle");
+      }
+    } else {
+      teardown();
+      setState("idle");
+    }
+  }, [state, teardown]);
+
+  const cancel = useCallback(() => {
+    if (
+      state !== "recording" &&
+      state !== "starting" &&
+      state !== "transcribing"
+    )
+      return;
+    cancelledRef.current = true;
+    if (
+      (activeProviderRef.current === "openai" ||
+        activeProviderRef.current === "google-realtime") &&
+      mediaRecorderRef.current
+    ) {
+      try {
+        mediaRecorderRef.current.stop();
+      } catch {
+        /* ignore */
+      }
+    } else if (speechRef.current) {
+      try {
+        speechRef.current.abort?.();
+      } catch {
+        /* ignore */
+      }
+    }
+    teardown();
+    setState("idle");
+  }, [state, teardown]);
+
+  // Auto-dismiss error after 8s so a stale "permission denied" message doesn't
+  // sit forever after the user fixes the underlying permission. Manual dismiss
+  // (via dismissError) and click-to-retry both also clear the error sooner.
+  useEffect(() => {
+    if (state !== "error") return;
+    const handle = setTimeout(() => {
+      setErrorMessage(null);
+      setState("idle");
+    }, 8000);
+    return () => clearTimeout(handle);
+  }, [state]);
+
+  const dismissError = useCallback(() => {
+    setErrorMessage(null);
+    if (state === "error") setState("idle");
+  }, [state]);
+
+  return {
+    state,
+    amplitude,
+    durationMs,
+    errorMessage,
+    provider,
+    supported,
+    start,
+    stop,
+    cancel,
+    dismissError,
+  };
+}