refactor(voice): load STT availability through React Query

useSpeechToText fetched `/api/settings/voice` inside an effect and stored
the result in useState behind a hand-rolled mountedRef guard: no cache, no
dedupe across mounts, and no AbortSignal, so the response was fetched and
parsed even after unmount. Two simultaneously mounted consumers issued two
requests. It also bypassed hooks/queries/**, which is where every other
server read in the app lives — and it escaped `check:react-query`, whose
audit only covers useQuery/useMutation call sites.

The value is server env read at request time, so it cannot change within a
session; the new hook uses an infinite staleTime and a caller-controlled
`enabled` so clients without the audio APIs never issue the request.

Hydration is unchanged: SSR renders unavailable, and the first client
render still resolves unavailable because `data` is undefined until the
fetch settles. No initialData, deliberately — adding it would break that.

mountedRef stays; it is still load-bearing for the streaming lifecycle.

Author: waleedlatif1

apps/sim/hooks/queries/voice.test.tsx

@@ -0,0 +1,107 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { act, type ReactNode } from 'react'
+import { sleep } from '@sim/utils/helpers'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { createRoot, type Root } from 'react-dom/client'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const { mockRequestJson } = vi.hoisted(() => ({ mockRequestJson: vi.fn() }))
+
+vi.mock('@/lib/api/client/request', () => ({ requestJson: mockRequestJson }))
+
+import { useVoiceSettings, voiceSettingsKeys } from '@/hooks/queries/voice'
+
+function renderHookWithClient<T>(useHook: () => T): { getResult: () => T } {
+  ;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+  const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } })
+  const container = document.createElement('div')
+  const root: Root = createRoot(container)
+  let result: T | undefined
+
+  function Probe() {
+    result = useHook()
+    return null
+  }
+
+  act(() => {
+    root.render(
+      <QueryClientProvider client={queryClient}>{(<Probe />) as ReactNode}</QueryClientProvider>
+    )
+  })
+
+  return {
+    getResult: () => {
+      if (result === undefined) throw new Error('Hook result is not ready')
+      return result
+    },
+  }
+}
+
+async function flush() {
+  await act(async () => {
+    for (let i = 0; i < 5; i++) {
+      await Promise.resolve()
+      await sleep(1)
+    }
+  })
+}
+
+beforeEach(() => {
+  vi.clearAllMocks()
+})
+
+describe('useVoiceSettings', () => {
+  it('keys the query under the voiceSettings namespace', () => {
+    expect(voiceSettingsKeys.settings()).toEqual(['voiceSettings', 'settings'])
+  })
+
+  it('reports availability from the server response', async () => {
+    mockRequestJson.mockResolvedValue({ sttAvailable: true })
+
+    const { getResult } = renderHookWithClient(() => useVoiceSettings())
+    await flush()
+
+    expect(getResult().data).toBe(true)
+    expect(mockRequestJson).toHaveBeenCalledTimes(1)
+  })
+
+  /**
+   * Consumers gate on a browser capability; a client that cannot stream audio
+   * should never issue the request at all.
+   */
+  it('issues no request when disabled', async () => {
+    mockRequestJson.mockResolvedValue({ sttAvailable: true })
+
+    const { getResult } = renderHookWithClient(() => useVoiceSettings({ enabled: false }))
+    await flush()
+
+    expect(mockRequestJson).not.toHaveBeenCalled()
+    expect(getResult().data).toBeUndefined()
+  })
+
+  /** A failed capability probe must read as unavailable, not throw. */
+  it('leaves data undefined when the request fails', async () => {
+    mockRequestJson.mockRejectedValue(new Error('offline'))
+
+    const { getResult } = renderHookWithClient(() => useVoiceSettings())
+    await flush()
+
+    expect(getResult().data).toBeUndefined()
+    expect(getResult().isError).toBe(true)
+  })
+
+  it('dedupes across simultaneous consumers', async () => {
+    mockRequestJson.mockResolvedValue({ sttAvailable: true })
+
+    renderHookWithClient(() => {
+      useVoiceSettings()
+      useVoiceSettings()
+      return null
+    })
+    await flush()
+
+    expect(mockRequestJson).toHaveBeenCalledTimes(1)
+  })
+})

apps/sim/hooks/queries/voice.ts

@@ -0,0 +1,42 @@
+import { useQuery } from '@tanstack/react-query'
+import { requestJson } from '@/lib/api/client/request'
+import { getVoiceSettingsContract } from '@/lib/api/contracts'
+
+/**
+ * Query key factory for voice capability queries
+ */
+export const voiceSettingsKeys = {
+  all: ['voiceSettings'] as const,
+  settings: () => [...voiceSettingsKeys.all, 'settings'] as const,
+}
+
+/**
+ * `/api/settings/voice` reports whether the server has an STT provider
+ * configured, which is read from env at request time and so cannot change
+ * within a session.
+ */
+export const VOICE_SETTINGS_STALE_TIME = Number.POSITIVE_INFINITY
+
+async function fetchSttAvailable(signal?: AbortSignal): Promise<boolean> {
+  const data = await requestJson(getVoiceSettingsContract, { signal })
+  return data.sttAvailable === true
+}
+
+/**
+ * Loads whether server-side speech-to-text is configured.
+ *
+ * `enabled` is caller-controlled so consumers gated on a browser capability
+ * skip the request entirely on clients that could not use STT anyway.
+ *
+ * Deliberately no `initialData`: consumers derive their support flag from
+ * `data === true`, so the first client render matches the server render
+ * (unavailable) until the fetch resolves.
+ */
+export function useVoiceSettings(options?: { enabled?: boolean }) {
+  return useQuery({
+    queryKey: voiceSettingsKeys.settings(),
+    queryFn: ({ signal }) => fetchSttAvailable(signal),
+    enabled: options?.enabled ?? true,
+    staleTime: VOICE_SETTINGS_STALE_TIME,
+  })
+}

apps/sim/hooks/use-speech-to-text.ts

@@ -4,7 +4,6 @@ import { useCallback, useEffect, useRef, useState } from 'react'
 import { createLogger } from '@sim/logger'
 import { isApiClientError } from '@/lib/api/client/errors'
 import { requestJson } from '@/lib/api/client/request'
-import { getVoiceSettingsContract } from '@/lib/api/contracts/common'
 import { speechTokenContract } from '@/lib/api/contracts/media/speech'
 import { arrayBufferToBase64, floatTo16BitPCM } from '@/lib/speech/audio'
 import {
@@ -13,6 +12,7 @@ import {
   MAX_SESSION_MS,
   SAMPLE_RATE,
 } from '@/lib/speech/config'
+import { useVoiceSettings } from '@/hooks/queries/voice'
 
 const logger = createLogger('useSpeechToText')
 
@@ -45,7 +45,19 @@ export function useSpeechToText({
   workspaceId,
 }: UseSpeechToTextProps): UseSpeechToTextReturn {
   const [isListening, setIsListening] = useState(false)
-  const [isSupported, setIsSupported] = useState(false)
+
+  /**
+   * Gate the capability request on the browser APIs streaming needs, so clients
+   * that could not use STT anyway never issue it.
+   */
+  const browserSupportsAudioCapture =
+    typeof window !== 'undefined' &&
+    typeof AudioContext !== 'undefined' &&
+    typeof WebSocket !== 'undefined' &&
+    typeof navigator?.mediaDevices?.getUserMedia === 'function'
+
+  const { data: sttAvailable } = useVoiceSettings({ enabled: browserSupportsAudioCapture })
+  const isSupported = browserSupportsAudioCapture && sttAvailable === true
   const [permissionState, setPermissionState] = useState<PermissionState>('prompt')
 
   const onTranscriptRef = useRef(onTranscript)
@@ -72,27 +84,6 @@ export function useSpeechToText({
   languageRef.current = language
   workspaceIdRef.current = workspaceId
 
-  useEffect(() => {
-    const browserOk =
-      typeof window !== 'undefined' &&
-      typeof AudioContext !== 'undefined' &&
-      typeof WebSocket !== 'undefined' &&
-      typeof navigator?.mediaDevices?.getUserMedia === 'function'
-
-    if (!browserOk) {
-      setIsSupported(false)
-      return
-    }
-
-    requestJson(getVoiceSettingsContract, {})
-      .then((data) => {
-        if (mountedRef.current) setIsSupported(data.sttAvailable === true)
-      })
-      .catch(() => {
-        if (mountedRef.current) setIsSupported(false)
-      })
-  }, [])
-
   const flushAudioBuffer = useCallback(() => {
     const ws = wsRef.current
     if (!ws || ws.readyState !== WebSocket.OPEN) return