The best way to control Claude Code, Codex and more from any computer or phone
Mirrored from https://github.com/Camo67/t3code.git
Synced Nov 22, 02:00 UTC
fix(web): make first-run dictation setup discoverable (#32197)
Co-authored-by: Lakshmi Tanmay <lakshmi@voltcrash.com> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Julius Marminge committed
Nov 6, 2026 at 21:51 UTC
4bd82b2177e682f10c138a8aa11dc96133679121
8 files changed
+110
-50
apps/web/src/components/preview/PreviewAnnotationSpeech.tsx
+1
@@ -61,6 +61,7 @@ export function PreviewAnnotationSpeech({
61
projectName: project?.title,
62
ownerKey: JSON.stringify(["preview-annotation", threadRef, tabId, config.sessionId]),
63
draftText: text,
64
+ offerSetup: false,
65
readDraft: () => ({
66
text: draft.current.text,
67
selection: { start: draft.current.cursor, end: draft.current.selectionEnd },
apps/web/src/components/settings/CloudVoiceConfiguration.tsx
+3
-2
@@ -38,7 +38,7 @@ import {
38
import {
39
chooseAudioDestination,
40
pendingCloudAudioChoice,
41
- useAudioGrant,
41
+ useAudioChoice,
42
} from "../../speech/voiceConsent";
43
import type { EnvironmentPresentation } from "../../state/environments";
44
import { useEnvironmentScope, usePreparedConnection } from "../../state/session";
@@ -172,7 +172,8 @@ export function CloudVoiceConfiguration({
172
routed && canUse ? prepared : null,
173
getCloudSpeechModels,
174
);
175
- const grant = useAudioGrant();
175
+ const choice = useAudioChoice();
176
+ const grant = choice === "off" ? null : choice;
177
const currentModel =
178
active && grant?.destination.kind === "cloud" && grant.destination.provider === "openrouter"
179
? grant.destination.model
apps/web/src/components/settings/VoiceSettingsPanel.browser.test.tsx
+21
-3
@@ -14,12 +14,15 @@ import {
14
useVoiceTranscriptionDestination,
15
} from "../../speech/useEnvironmentSpeechInput";
16
import { chooseAudioDestination, chooseTranscriptCleanup } from "../../speech/voiceConsent";
17
+import { useEnvironmentScope } from "../../state/session";
18
import { toastManager } from "../ui/toast";
19
import { SettingsScopeProvider } from "./SettingsScopeContext";
20
import { SpeechLanguageSelect } from "./SpeechLanguageSelect";
21
import { VoiceSettingsPanel } from "./VoiceSettingsPanel";
22
23
vi.mock(import("../../speech/useEnvironmentSpeechInput"), { spy: true });
24
+vi.mock(import("../../state/session"), { spy: true });
25
+
26
// The real connection runtime authorizes relay requests with a signed-in cloud session.
27
vi.mock("../../connection/runtime", async () => {
28
const [{ ManagedRelay }, rpc, { Atom }, Context, Effect, Layer] = await Promise.all([
@@ -68,7 +71,7 @@ vi.mock("../../connection/runtime", async () => {
71
};
72
});
73
71
-it("preserves the model test transcript when its model is filtered out", async () => {
74
+it("tests the selected model after download and preserves its transcript across filters", async () => {
75
const target = new PrimaryConnectionTarget({
76
environmentId: EnvironmentId.make("voice-filter"),
77
label: "Test environment",
@@ -103,15 +106,23 @@ it("preserves the model test transcript when its model is filtered out", async (
106
modelUnloadTimeout: "never",
107
gpuDevices: [],
108
} satisfies EnvironmentSpeechStatus;
109
+ let installed = false;
110
const fetch = globalThis.fetch;
111
using _network = vi.spyOn(globalThis, "fetch").mockImplementation((input, init) => {
112
const url = new URL(input instanceof Request ? input.url : input, window.location.href);
109
- if (url.pathname === "/api/voice/status") return Promise.resolve(Response.json(status));
113
+ if (url.pathname === "/api/voice/status")
114
+ return Promise.resolve(
115
+ Response.json(installed ? status : { ...status, state: "missing-model" }),
116
+ );
117
+ if (url.pathname === "/api/voice/models/download") {
118
+ installed = true;
119
+ return Promise.resolve(Response.json({ models: [model] }));
120
+ }
121
if (url.pathname === "/api/voice/models")
122
return Promise.resolve(
123
Response.json({
124
models: [
114
- model,
125
+ installed ? model : { ...model, state: "downloadable", active: false },
126
{
127
...model,
128
id: "both",
@@ -136,6 +147,7 @@ it("preserves the model test transcript when its model is filtered out", async (
147
return fetch(input, init);
148
});
149
const transcript = "Keep this transcript.";
150
+ using _scope = vi.mocked(useEnvironmentScope).mockReturnValue(true);
151
await vi.mocked(useVoiceTranscriptionDestination).withImplementation(
152
() => ({ environmentId: target.environmentId, label: target.label, grantId: "test", prepared }),
153
async () => {
@@ -177,7 +189,13 @@ it("preserves the model test transcript when its model is filtered out", async (
189
</SettingsScopeProvider>,
190
);
191
const testModel = screen.getByRole("button", { name: "Test model", exact: true });
192
+ const download = screen.getByRole("button", { name: "Download", exact: true });
193
+ await expect.element(download).toBeVisible();
194
+ expect(testModel.query()).toBeNull();
195
+ expect(screen.getByRole("button", { name: "Set up voice input" }).query()).toBeNull();
196
+ await userEvent.click(download);
197
await expect.element(testModel).toBeVisible();
198
+ expect(screen.getByRole("button", { name: "Set up voice input" }).query()).toBeNull();
199
await userEvent.click(testModel);
200
const result = screen.getByRole("status", { name: "Test transcript" });
201
await expect.element(result).toHaveTextContent(transcript);
apps/web/src/speech/useEnvironmentSpeechInput.browser.test.tsx
+38
-24
@@ -178,6 +178,7 @@ const THREAD_ENV = "thread-env";
178
function setup(options: { readonly destination?: string | null } = {}) {
179
mocks.settings = {};
180
setDestination(options.destination ?? null);
181
+ if (!options.destination) localStorage.removeItem("t3code:voice-audio-grant:v1");
182
chooseTranscriptCleanup(false);
183
mocks.primaryEnvironmentId = "primary-env";
184
mocks.connected = new Set(["primary-env", THREAD_ENV, "env-a", "env-b"]);
@@ -243,15 +244,22 @@ it.each([
244
["nothing is configured", {}],
245
// A transcription host picked by an earlier PoC build is not consent.
246
["a legacy transcription host is configured", { voiceTranscriptionEnvironmentId: "env-a" }],
246
-])("stays local-only when %s, even with voice-capable environments", async (_, legacy) => {
247
+])("opens destination setup without sending audio when %s", async (_, legacy) => {
248
setup();
249
mocks.settings = { ...legacy, speechSilenceFiltering: true };
249
- await using _screen = await render(<Probe />);
250
+ await using screen = await render(<Probe />);
251
+ // The composer mic and the dictation shortcut both gate on this.
252
+ expect(mocks.voice.available).toBe(true);
253
await act(() => mocks.voice.start());
254
+ expect(screen.router?.state.location).toMatchObject({
255
+ pathname: "/settings/voice",
256
+ hash: "voice-transcription-destination",
257
+ });
258
expectNoAudioSent();
259
expect(mocks.committed).not.toHaveBeenCalled();
253
- expect(mocks.voice.available).toBe(false);
260
+ expect(mocks.voice.state.phase).toBe("idle");
261
expect(mocks.voice.transcriptionEnvironmentId).toBeNull();
262
+ expect(localStorage.getItem("t3code:voice-audio-grant:v1")).toBeNull();
263
});
264
265
it.each([true, false])(
@@ -302,6 +310,7 @@ it.each([
310
expect(mocks.voice.state.phase).toBe("recording");
311
setDestination(next);
312
await screen.rerender(<Probe />);
313
+ if (next === null) expect(mocks.voice.available).toBe(false);
314
expect(mocks.voice.state.phase).toBe("idle");
315
await act(() => mocks.voice.stop());
316
expect(mocks.transcribeCalls).toEqual([]);
@@ -390,7 +399,7 @@ it("revokes across windows even before the storage event and survives stale pref
399
expect(storage.getItem(key)).toBeNull();
400
expect(canSend()).toBe(false);
401
writeBrowserClientSettings({ ...DEFAULT_CLIENT_SETTINGS, wordWrap: false });
393
- await vi.waitFor(() => expect(mocks.voice.available).toBe(false));
402
+ await vi.waitFor(() => expect(mocks.voice.transcriptionEnvironmentId).toBeNull());
403
expect(mocks.voice.state.phase).toBe("idle");
404
await act(() => mocks.voice.stop());
405
expect(mocks.transcribeCalls).toEqual([]);
@@ -401,26 +410,30 @@ it("revokes across windows even before the storage event and survives stale pref
410
}
411
});
412
404
-it("recovers from a corrupt choice without enabling cloud dictation before the save completes", async () => {
405
- setup();
406
- mocks.cloudVoiceCapable.add("env-b");
407
- mocks.modelState = "missing-model";
408
- window.localStorage.setItem("t3code:voice-audio-grant:v1", "not-json");
409
- const save = pendingCloudAudioChoice({
410
- kind: "cloud",
411
- environmentId: EnvironmentId.make("env-b"),
412
- provider: "xai",
413
- });
414
- await using _screen = await render(<Probe />);
415
- expect(mocks.voice.transcriptionEnvironmentId).toBeNull();
416
- await act(() => mocks.voice.start());
417
- expectNoAudioSent();
418
- await act(save);
419
- await act(() => mocks.voice.start());
420
- await act(() => mocks.voice.stop());
421
- expect(mocks.transcribeCalls).toEqual(["xai via env-b"]);
422
- expect(mocks.statusRequests).toEqual([]);
423
-});
413
+it.each(["not-json", JSON.stringify("off")])(
414
+ "does not enable a pending provider over %s before the save completes",
415
+ async (previous) => {
416
+ setup();
417
+ mocks.cloudVoiceCapable.add("env-b");
418
+ mocks.modelState = "missing-model";
419
+ window.localStorage.setItem("t3code:voice-audio-grant:v1", previous);
420
+ const save = pendingCloudAudioChoice({
421
+ kind: "cloud",
422
+ environmentId: EnvironmentId.make("env-b"),
423
+ provider: "xai",
424
+ });
425
+ await using _screen = await render(<Probe />);
426
+ expect(mocks.voice.transcriptionEnvironmentId).toBeNull();
427
+ if (previous === JSON.stringify("off")) expect(mocks.voice.available).toBe(false);
428
+ await act(() => mocks.voice.start());
429
+ expectNoAudioSent();
430
+ await act(save);
431
+ await act(() => mocks.voice.start());
432
+ await act(() => mocks.voice.stop());
433
+ expect(mocks.transcribeCalls).toEqual(["xai via env-b"]);
434
+ expect(mocks.statusRequests).toEqual([]);
435
+ },
436
+);
437
438
it("sends audio to OpenRouter only under a device grant naming the exact model", async () => {
439
setup();
@@ -468,6 +481,7 @@ it("uses neither destination when the cloud save marker cannot be read", async (
481
await using _screen = await render(<Probe />);
482
expect(mocks.voice.transcriptionEnvironmentId).toBeNull();
483
expect(canSendToPrevious()).toBe(false);
484
+ expect(mocks.voice.available).toBe(false);
485
await act(() => mocks.voice.start());
486
expectNoAudioSent();
487
});
apps/web/src/speech/useEnvironmentSpeechInput.ts
+25
-6
@@ -23,6 +23,7 @@ import type {
23
} from "@t3tools/contracts";
24
import { resolveProjectSettings } from "@t3tools/shared/projectSettings";
25
import { resolveSpeechVocabulary } from "@t3tools/shared/speech";
26
+import { useNavigate } from "@tanstack/react-router";
27
import * as Option from "effect/Option";
28
import { useEffect, useRef, useState } from "react";
29
@@ -37,7 +38,7 @@ import { useEnvironment } from "../state/environments";
38
import { useEnvironmentScope, usePreparedConnection } from "../state/session";
39
import { createBrowserVoiceInputPlatform } from "./browserVoiceInput";
40
import { runEnvironmentSpeech } from "./runEnvironmentSpeech";
40
-import { bindAudioGrant, readCleanupGrant, useAudioGrant } from "./voiceConsent";
41
+import { bindAudioGrant, readCleanupGrant, useAudioChoice } from "./voiceConsent";
42
43
const INITIAL_STATE: VoiceInputState = { phase: "idle", error: null, errorAction: null };
44
const WAITING_STATE: VoiceInputState = { phase: "preparing", error: null, errorAction: null };
@@ -88,6 +89,11 @@ type HookInput = {
89
readonly ownerKey: string;
90
readonly draftText: string;
91
readonly disabled?: boolean | undefined;
92
+ /**
93
+ * Until a destination is chosen, voice input is offered and its first gesture opens Voice
94
+ * settings. False hides it instead, for editors whose draft would not survive the navigation.
95
+ */
96
+ readonly offerSetup?: boolean | undefined;
97
/** False keeps the transcript off the cleanup provider even when cleanup is on; the model test uses it. */
98
readonly cleanup?: boolean | undefined;
99
readonly readDraft: () => DraftInput;
@@ -104,7 +110,8 @@ type HookInput = {
110
*/
111
export function useVoiceTranscriptionDestination() {
112
const hydrated = useClientSettingsHydrated();
107
- const grant = useAudioGrant();
113
+ const choice = useAudioChoice();
114
+ const grant = choice === "off" ? null : choice;
115
const environmentId = hydrated && grant ? grant.destination.environmentId : null;
116
const environment = useEnvironment(environmentId);
117
const connection = Option.getOrNull(usePreparedConnection(environmentId));
@@ -117,6 +124,7 @@ export function useVoiceTranscriptionDestination() {
124
provider ? "cloudVoiceTranscription" : "voiceTranscription"
125
] === true;
126
return {
127
+ ...(hydrated && choice === null ? { offerFirstRunSetup: true } : {}),
128
environmentId,
129
...(provider ? { cloudProvider: provider } : {}),
130
...(model ? { cloudModel: model } : {}),
@@ -130,6 +138,7 @@ export function useVoiceTranscriptionDestination() {
138
}
139
140
export function useEnvironmentSpeechInput(input: HookInput) {
141
+ const navigate = useNavigate();
142
const destination = useVoiceTranscriptionDestination();
143
const prepared = destination.prepared;
144
const grantId = destination.grantId;
@@ -437,10 +446,16 @@ export function useEnvironmentSpeechInput(input: HookInput) {
446
});
447
448
const start = useStableCallback(async () => {
449
+ if (latestRef.current.input.disabled) return;
450
+ if (!grantId) {
451
+ if (destination.offerFirstRunSetup && latestRef.current.input.offerSetup !== false)
452
+ await navigate({ to: "/settings/voice", hash: "voice-transcription-destination" });
453
+ return;
454
+ }
455
const request = ++startRequestRef.current;
456
const controller = controllerRef.current;
457
const owner = latestRef.current.input.ownerKey;
443
- if (latestRef.current.input.disabled || !controller || !prepared) return;
458
+ if (!controller || !prepared) return;
459
if (cloudProvider) {
460
setLevel(0);
461
await controller.start();
@@ -529,11 +544,15 @@ export function useEnvironmentSpeechInput(input: HookInput) {
544
}
545
});
546
547
+ const destinationReady =
548
+ grantId === null
549
+ ? Boolean(destination.offerFirstRunSetup) && input.offerSetup !== false
550
+ : prepared !== null &&
551
+ (cloudProvider !== undefined ||
552
+ (status?.prepared === prepared && status.value?.supported !== false));
553
return {
554
available:
534
- prepared !== null &&
535
- (cloudProvider !== undefined ||
536
- (status?.prepared === prepared && status.value?.supported !== false)) &&
555
+ destinationReady &&
556
typeof navigator !== "undefined" &&
557
Boolean(navigator.mediaDevices?.getUserMedia) &&
558
typeof AudioWorkletNode !== "undefined",
apps/web/src/speech/useTextFieldSpeech.tsx
+1
@@ -33,6 +33,7 @@ export function useTextFieldSpeech(input: {
33
ownerKey: input.ownerKey,
34
draftText: input.text,
35
disabled: input.disabled,
36
+ offerSetup: false,
37
readDraft: () => {
38
const field = latest.current.textareaRef.current;
39
const cursor = field?.selectionStart ?? latest.current.text.length;
apps/web/src/speech/voiceConsent.ts
+15
-12
@@ -16,13 +16,15 @@ const CLEANUP_KEY = "t3code:voice-cleanup-grant:v1";
16
const Grant = Schema.Struct({ id: Schema.String, destination: VoiceTranscriptionDestination });
17
const AudioGrant = Schema.NullOr(Grant);
18
const sameGrant = Schema.toEquivalence(AudioGrant);
19
-const AudioChoice = Schema.NullOr(
20
- Schema.Union([Grant, Schema.Struct({ pending: Grant, previous: AudioGrant })]),
21
-);
19
+const SavedChoice = Schema.Union([AudioGrant, Schema.Literal("off")]);
20
+const AudioChoice = Schema.Union([
21
+ SavedChoice,
22
+ Schema.Struct({ pending: Grant, previous: SavedChoice }),
23
+]);
24
type AudioChoice = typeof AudioChoice.Type;
25
const savedKey = (id: string) => `${AUDIO_KEY}:saved:${id}`;
26
const pendingGrant = (choice: AudioChoice) =>
25
- choice && "pending" in choice ? choice.pending : null;
27
+ choice && choice !== "off" && "pending" in choice ? choice.pending : null;
28
const CleanupGrant = Schema.NullOr(Schema.String);
29
const decodeChoice = Schema.decodeSync(Schema.fromJsonString(AudioChoice));
30
const readChoice = () => readLocalStorageValue(AUDIO_KEY, null, AudioChoice);
@@ -35,14 +37,14 @@ function readSaveMarker(id: string | undefined) {
37
}
38
}
39
38
-function activeGrant(choice: AudioChoice, marker: string | null | undefined) {
39
- if (!choice || !("pending" in choice)) return choice;
40
+function activeChoice(choice: AudioChoice, marker: string | null | undefined) {
41
+ if (!choice || choice === "off" || !("pending" in choice)) return choice;
42
// Only a confirmed missing marker means the previous grant still applies.
43
if (marker === null) return choice.previous;
42
- return marker === "true" ? choice.pending : null;
44
+ return marker === "true" ? choice.pending : ("off" as const);
45
}
46
45
-export function useAudioGrant() {
47
+export function useAudioChoice() {
48
const [choice] = useLocalStorage(AUDIO_KEY, null, AudioChoice);
49
const id = pendingGrant(choice)?.id;
50
const marker = useSyncExternalStore(
@@ -50,7 +52,7 @@ export function useAudioGrant() {
52
() => readSaveMarker(id),
53
() => undefined,
54
);
53
- return activeGrant(choice, marker);
55
+ return activeChoice(choice, marker);
56
}
57
58
function replaceChoice(choice: AudioChoice, previous = readChoice()) {
@@ -61,7 +63,7 @@ function replaceChoice(choice: AudioChoice, previous = readChoice()) {
63
}
64
65
export function chooseAudioDestination(destination: VoiceTranscriptionDestination | null) {
64
- replaceChoice(destination && { id: randomUUID(), destination });
66
+ replaceChoice(destination ? { id: randomUUID(), destination } : "off");
67
}
68
69
export function pendingCloudAudioChoice(
@@ -70,7 +72,7 @@ export function pendingCloudAudioChoice(
72
const choice = readChoice();
73
const pending = { id: randomUUID(), destination };
74
replaceChoice(
73
- { pending, previous: activeGrant(choice, readSaveMarker(pendingGrant(choice)?.id)) },
75
+ { pending, previous: activeChoice(choice, readSaveMarker(pendingGrant(choice)?.id)) },
76
choice,
77
);
78
// A late response can acknowledge only its own choice, never write the destination another tab picked.
@@ -91,7 +93,8 @@ export function bindAudioGrant(id: string) {
93
choice = raw ? decodeChoice(raw) : null;
94
cachedRaw = raw;
95
}
94
- return activeGrant(choice, readSaveMarker(pendingGrant(choice)?.id));
96
+ const active = activeChoice(choice, readSaveMarker(pendingGrant(choice)?.id));
97
+ return active === "off" ? null : active;
98
};
99
const bound = current();
100
if (bound?.id !== id) return () => false;
docs/user/voice-input.md
+6
-3
@@ -15,6 +15,7 @@ to a named environment on that phone, open **Settings → Voice → Transcribe o
15
On web and desktop, you choose where transcription runs.
16
Nothing is sent until you choose one: open **Settings → Voice** and set
17
**Transcribe with** to the environment that should transcribe for you.
18
+On a new device, the microphone or dictation shortcut opens that setting from the composer.
19
Microphone audio recorded on this device is sent to that environment over your
20
authenticated connection, transcribed there, and discarded. The choice is saved
21
on this device only, so every computer and browser you use asks for it once.
@@ -48,9 +49,11 @@ until you choose another.
49
50
## Set up a model
51
51
-If you choose environment transcription, T3 Code offers to download the recommended
52
-English model to that environment. In **Settings → Voice → Transcription**, select
53
-the languages you dictate in to compare models that support all of them.
52
+In **Settings → Voice → Transcription**, download a model and choose **Use model** if it
53
+isn’t already selected. **Test model** lets you try it without sending a message.
54
+If you use the composer microphone before a model is installed, it offers to download one.
55
+
56
+Select the languages you dictate in to compare models that support all of them.
57
Accuracy shows how often the model got words or characters wrong in each
58
language; speed is the time to transcribe 30 seconds on a reference GPU. Choose
59
**All languages** to browse the full catalog. Filtering does not switch your model.