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 21, 21:00 UTC
fix(mobile): screen readers hear when the open thread needs you or finishes (#34431)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
shivam committed
Nov 12, 2026 at 06:58 UTC
7d71f852a8edd298ffde67c295760c286a71a27c
12 files changed
+270
-5
apps/mobile/src/features/threads/ThreadRouteScreen.tsx
+20
@@ -28,6 +28,7 @@ import {
28
AuthTerminalReadScope,
29
DEFAULT_SERVER_SETTINGS,
30
EnvironmentId,
31
+ isProviderNativeSubagentThread,
32
MessageId,
33
ThreadId,
34
type ProjectScript,
@@ -122,6 +123,7 @@ import {
123
type ThreadInspectorPresentation,
124
} from "./thread-inspector-preview";
125
import { useStartSideChat } from "./useStartSideChat";
126
+import { useThreadStatusAnnouncements } from "./useThreadStatusAnnouncements";
127
import type { ThreadInspectorMode, ThreadInspectorTarget } from "./thread-inspector-navigation";
128
import { useSelectWorkspaceDetail } from "../layout/workspace/useSelectWorkspaceDetail";
129
@@ -377,6 +379,24 @@ function ThreadRouteContent(
379
const gitState = useSelectedThreadGitState();
380
const gitActions = useSelectedThreadGitActions();
381
const requests = useSelectedThreadRequests();
382
+ useThreadStatusAnnouncements({
383
+ threadKey:
384
+ selectedThread === null || isProviderNativeSubagentThread(selectedThread.source)
385
+ ? null
386
+ : scopedThreadKey(selectedThread.environmentId, selectedThread.id),
387
+ // A preview beside its host names its thread, so the two threads' statuses can't be confused.
388
+ subject:
389
+ props.inspectorPresentation !== undefined && "onMaximize" in props.inspectorPresentation
390
+ ? (selectedThread?.title ?? null)
391
+ : null,
392
+ approvalRequestId: requests.activePendingApproval?.requestId ?? null,
393
+ userInputRequestId: requests.activePendingUserInput?.requestId ?? null,
394
+ shellRequestId: selectedThread?.source.pendingRuntimeRequest?.id ?? null,
395
+ shellPendingUserInput: selectedThread?.hasPendingUserInput === true,
396
+ working: composer.activeWorkStartedAt !== null || composer.isCompacting,
397
+ run: composer.selectedThreadAnnouncedRun,
398
+ detailBehind: composer.selectedThreadDetailBehindShell,
399
+ });
400
const interruptThreadTurn = useAtomCommand(threadEnvironment.interruptTurn, "thread interrupt");
401
const resumeThreadQueue = useAtomCommand(threadEnvironment.resumeThreadQueue, {
402
label: "resume queue",
apps/mobile/src/features/threads/threadStatusAnnouncement.test.ts
new
+82
@@ -0,0 +1,82 @@
1
+import {
2
+ nextThreadAnnouncement,
3
+ type ThreadAnnouncementMemory,
4
+} from "@t3tools/client-runtime/state/thread-activity-announcement";
5
+import { RunId } from "@t3tools/contracts";
6
+import { describe, expect, it } from "vite-plus/test";
7
+
8
+import {
9
+ nextThreadActivitySnapshot,
10
+ type ThreadActivityInput,
11
+ type ThreadActivityMemory,
12
+} from "./threadStatusAnnouncement";
13
+
14
+const run = RunId.make("run-1");
15
+
16
+/** A frame of a working turn: what the question card shows and what the shell holds. */
17
+function frame(card: string | null, shell: string | null): ThreadActivityInput {
18
+ return {
19
+ approvalRequestId: null,
20
+ userInputRequestId: card,
21
+ shellRequestId: shell,
22
+ shellPendingUserInput: shell !== null,
23
+ working: true,
24
+ run: { runId: run, status: "running" },
25
+ };
26
+}
27
+
28
+const idle: ThreadActivityInput = { ...frame(null, null), working: false, run: null };
29
+const done: ThreadActivityInput = {
30
+ ...frame(null, null),
31
+ working: false,
32
+ run: { runId: run, status: "completed" },
33
+};
34
+
35
+function announcements(frames: ReadonlyArray<ThreadActivityInput>): ReadonlyArray<string | null> {
36
+ let activity: ThreadActivityMemory | null = null;
37
+ let memory: ThreadAnnouncementMemory | null = null;
38
+ return frames.map((input) => {
39
+ activity = nextThreadActivitySnapshot(activity, input);
40
+ const next = nextThreadAnnouncement(memory, activity.snapshot);
41
+ memory = next.memory;
42
+ return next.announcement;
43
+ });
44
+}
45
+
46
+describe("nextThreadActivitySnapshot", () => {
47
+ it("says each question once while the card and the shell catch up at different times", () => {
48
+ expect(
49
+ announcements([
50
+ idle,
51
+ frame(null, null),
52
+ // The card shows question A before the shell has it.
53
+ frame("a", null),
54
+ frame("a", "a"),
55
+ // Answered: the card hides A at once, the shell still holds it.
56
+ frame(null, "a"),
57
+ // Question B reaches the card while the shell still holds A, and is answered before the shell has B.
58
+ frame("b", "a"),
59
+ frame(null, "a"),
60
+ frame(null, "b"),
61
+ frame(null, null),
62
+ // A secret request shows only in the shell.
63
+ frame(null, "secret"),
64
+ frame(null, null),
65
+ done,
66
+ ]),
67
+ ).toEqual([
68
+ null,
69
+ "Working",
70
+ "Needs your input",
71
+ null,
72
+ null,
73
+ "Needs your input",
74
+ null,
75
+ null,
76
+ null,
77
+ "Needs your input",
78
+ null,
79
+ "Done",
80
+ ]);
81
+ });
82
+});
apps/mobile/src/features/threads/threadStatusAnnouncement.ts
new
+53
@@ -0,0 +1,53 @@
1
+import type { ThreadActivitySnapshot } from "@t3tools/client-runtime/state/thread-activity-announcement";
2
+import type { RunId, OrchestrationV2RunStatus } from "@t3tools/contracts";
3
+
4
+export interface ThreadActivityInput {
5
+ readonly approvalRequestId: string | null;
6
+ readonly userInputRequestId: string | null;
7
+ /** The thread shell's pending request, which secret and link cards have only there. */
8
+ readonly shellRequestId: string | null;
9
+ readonly shellPendingUserInput: boolean;
10
+ readonly working: boolean;
11
+ readonly run: { readonly runId: RunId; readonly status: OrchestrationV2RunStatus } | null;
12
+}
13
+
14
+export interface ThreadActivityMemory {
15
+ readonly snapshot: ThreadActivitySnapshot;
16
+ /** Requests the thread screen has shown as a card. */
17
+ readonly cardRequestIds: ReadonlySet<string>;
18
+}
19
+
20
+/** What the open thread's screen reader status follows, from the same sources the thread screen shows. */
21
+export function nextThreadActivitySnapshot(
22
+ previous: ThreadActivityMemory | null,
23
+ input: ThreadActivityInput,
24
+): ThreadActivityMemory {
25
+ const { approvalRequestId, userInputRequestId, shellRequestId } = input;
26
+ const cardRequestId = approvalRequestId ?? userInputRequestId;
27
+ const seen = previous?.cardRequestIds ?? new Set<string>();
28
+ // A card leaves as soon as it is answered, before the shell; a shell request the card
29
+ // already showed is that answered one, so the request stays the one last announced.
30
+ // Secret and link requests never show as a card and come from the shell alone.
31
+ const requestId =
32
+ cardRequestId ??
33
+ (shellRequestId !== null && seen.has(shellRequestId)
34
+ ? (previous?.snapshot.requestId ?? null)
35
+ : shellRequestId);
36
+ return {
37
+ snapshot: {
38
+ status:
39
+ approvalRequestId !== null
40
+ ? "approval"
41
+ : userInputRequestId !== null || input.shellPendingUserInput
42
+ ? "input"
43
+ : input.working
44
+ ? "working"
45
+ : "idle",
46
+ requestId,
47
+ runId: input.run?.runId ?? null,
48
+ runStatus: input.run?.status ?? null,
49
+ },
50
+ cardRequestIds:
51
+ cardRequestId === null || seen.has(cardRequestId) ? seen : new Set([...seen, cardRequestId]),
52
+ };
53
+}
apps/mobile/src/features/threads/useThreadStatusAnnouncements.ts
new
+85
@@ -0,0 +1,85 @@
1
+import { useIsFocused } from "@react-navigation/native";
2
+import {
3
+ nextThreadAnnouncement,
4
+ type ThreadAnnouncementMemory,
5
+} from "@t3tools/client-runtime/state/thread-activity-announcement";
6
+import { useEffect, useRef } from "react";
7
+import { AccessibilityInfo } from "react-native";
8
+
9
+import { useAppActive } from "../../lib/appState";
10
+import {
11
+ nextThreadActivitySnapshot,
12
+ type ThreadActivityInput,
13
+ type ThreadActivityMemory,
14
+} from "./threadStatusAnnouncement";
15
+
16
+/** Tells VoiceOver and TalkBack when the open thread starts working, needs the user, or finishes. */
17
+export function useThreadStatusAnnouncements({
18
+ threadKey,
19
+ subject,
20
+ detailBehind,
21
+ approvalRequestId,
22
+ userInputRequestId,
23
+ shellRequestId,
24
+ shellPendingUserInput,
25
+ working,
26
+ run,
27
+}: ThreadActivityInput & {
28
+ /** Null when nothing should be announced, such as a provider subagent's thread. */
29
+ readonly threadKey: string | null;
30
+ /** The thread's title, said after each status when another thread is on screen beside it. */
31
+ readonly subject: string | null;
32
+ /** See isDetailBehindShell. */
33
+ readonly detailBehind: boolean;
34
+}) {
35
+ // A retained route stays mounted under the screen above it; it speaks only while shown,
36
+ // and starts from a silent baseline when it is shown again.
37
+ const focused = useIsFocused();
38
+ const appActive = useAppActive();
39
+ const activeKey = focused && appActive ? threadKey : null;
40
+ const memoryRef = useRef<{
41
+ threadKey: string;
42
+ activity: ThreadActivityMemory;
43
+ announcement: ThreadAnnouncementMemory;
44
+ } | null>(null);
45
+ const runId = run?.runId ?? null;
46
+ const runStatus = run?.status ?? null;
47
+
48
+ // oxlint-disable-next-line t3code/no-unreasoned-state-sync -- speaks committed status changes through the platform screen reader
49
+ useEffect(() => {
50
+ if (activeKey === null) {
51
+ memoryRef.current = null;
52
+ return;
53
+ }
54
+ if (detailBehind) return;
55
+ const previous = memoryRef.current?.threadKey === activeKey ? memoryRef.current : null;
56
+ const activity = nextThreadActivitySnapshot(previous?.activity ?? null, {
57
+ approvalRequestId,
58
+ userInputRequestId,
59
+ shellRequestId,
60
+ shellPendingUserInput,
61
+ working,
62
+ run: runId === null || runStatus === null ? null : { runId, status: runStatus },
63
+ });
64
+ const next = nextThreadAnnouncement(previous?.announcement ?? null, activity.snapshot);
65
+ memoryRef.current = { threadKey: activeKey, activity, announcement: next.memory };
66
+ // Queued, like the web's polite region, so VoiceOver doesn't cut off what it is reading.
67
+ if (next.announcement !== null) {
68
+ AccessibilityInfo.announceForAccessibilityWithOptions(
69
+ subject === null ? next.announcement : `${next.announcement}: ${subject}`,
70
+ { queue: true },
71
+ );
72
+ }
73
+ }, [
74
+ activeKey,
75
+ subject,
76
+ detailBehind,
77
+ approvalRequestId,
78
+ userInputRequestId,
79
+ shellRequestId,
80
+ shellPendingUserInput,
81
+ working,
82
+ runId,
83
+ runStatus,
84
+ ]);
85
+}
apps/mobile/src/state/use-thread-composer-state.ts
+15
@@ -8,10 +8,15 @@ import { threadRuntimeIsActive } from "@t3tools/client-runtime/state/shell";
8
import type { ThreadCheckpointSummary } from "@t3tools/client-runtime/state/thread-checkpoints";
9
import { threadSteersDuringCompaction } from "@t3tools/client-runtime/state/thread-workflows";
10
import { resolvePendingHandoff } from "@t3tools/client-runtime/handoff";
11
+import {
12
+ announcedRun,
13
+ isDetailBehindShell,
14
+} from "@t3tools/client-runtime/state/thread-activity-announcement";
15
import {
16
deriveProviderSubagentStatus,
17
deriveProviderExtensionStatuses,
18
deriveResumableRunId,
19
+ deriveLatestThreadRun,
20
deriveRunlessWorkStartedAt,
21
deriveThreadActivityRun,
22
deriveThreadRuntime,
@@ -335,6 +340,14 @@ export function useThreadComposerState(input: {
340
const selectedThreadActivityRun = selectedThreadProjection
341
? deriveThreadActivityRun(selectedThreadProjection.projection)
342
: (selectedThreadShell?.latestRun ?? null);
343
+ const selectedThreadAnnouncedRun = announcedRun(
344
+ selectedThreadActivityRun,
345
+ selectedThreadProjection?.projection.runs ?? [],
346
+ );
347
+ const selectedThreadDetailBehindShell = isDetailBehindShell(
348
+ selectedThreadProjection ? deriveLatestThreadRun(selectedThreadProjection.projection) : null,
349
+ selectedThreadShell?.latestRun ?? null,
350
+ );
351
352
const activeRunId =
353
selectedThreadRuntime?.activeRunId && threadRuntimeIsActive(selectedThreadRuntime)
@@ -881,6 +894,8 @@ export function useThreadComposerState(input: {
894
dismissFeedback,
895
selectedThreadFeed,
896
selectedThreadActivityRun,
897
+ selectedThreadAnnouncedRun,
898
+ selectedThreadDetailBehindShell,
899
selectedThreadQueueCount,
900
selectedThreadQueuedMessages,
901
dispatchingQueuedMessageId,
apps/web/src/components/ChatView.tsx
+4
-1
@@ -7,7 +7,10 @@ import { ScrollToEndButton, WorkspaceFileDropOverlay } from "./chat/TimelineOver
7
import { usePasteToFocusComposer } from "./chat/usePasteToFocusComposer";
8
import { useFocusComposerOnThreadOpen } from "./chat/useFocusComposerOnThreadOpen";
9
import { configuredHostedAppUrl } from "../hostedPairing";
10
-import { announcedRun, isDetailBehindShell } from "./chat/threadActivityAnnouncement";
10
+import {
11
+ announcedRun,
12
+ isDetailBehindShell,
13
+} from "@t3tools/client-runtime/state/thread-activity-announcement";
14
import {
15
deriveAvailableRevertTurnCounts,
16
deriveThreadPendingBackgroundTasks,
apps/web/src/components/backgroundThreadAnnouncement.ts
+4
-1
@@ -1,7 +1,10 @@
1
import type { OrchestrationV2RunStatus, RunId } from "@t3tools/contracts";
2
3
import type { SidebarThreadSummary } from "../types";
4
-import { runOutcomeText, THREAD_STATUS_TEXT } from "./chat/threadActivityAnnouncement";
4
+import {
5
+ runOutcomeText,
6
+ THREAD_STATUS_TEXT,
7
+} from "@t3tools/client-runtime/state/thread-activity-announcement";
8
9
export interface BackgroundThreadSnapshot {
10
readonly key: string;
apps/web/src/components/chat/ThreadActivityAnnouncer.tsx
+1
-1
@@ -8,7 +8,7 @@ import {
8
nextThreadAnnouncement,
9
type ThreadActivitySnapshot,
10
type ThreadAnnouncementMemory,
11
-} from "./threadActivityAnnouncement";
11
+} from "@t3tools/client-runtime/state/thread-activity-announcement";
12
import {
13
nextTurnDetailAnnouncement,
14
NO_TURN_DETAIL,
apps/web/src/components/chat/usePromptSuggestion.ts
+1
-1
@@ -6,7 +6,7 @@ import { useMediaQuery } from "../../hooks/useMediaQuery";
6
import { useServerConfigs } from "../../state/entities";
7
import { orchestrationEnvironment } from "../../state/orchestration";
8
import { useEnvironmentQuery } from "../../state/query";
9
-import { announcedRun } from "./threadActivityAnnouncement";
9
+import { announcedRun } from "@t3tools/client-runtime/state/thread-activity-announcement";
10
11
// Dismissed suggestions, keyed by environment and run, shared by every mounted composer and kept
12
// across remounts. Run ids derive from thread ids, which can repeat across environments.
packages/client-runtime/package.json
+4
@@ -335,6 +335,10 @@
335
"types": "./src/state/threads.ts",
336
"default": "./src/state/threads.ts"
337
},
338
+ "./state/thread-activity-announcement": {
339
+ "types": "./src/state/threadActivityAnnouncement.ts",
340
+ "default": "./src/state/threadActivityAnnouncement.ts"
341
+ },
342
"./state/subagent-display": {
343
"types": "./src/state/subagentDisplay.ts",
344
"default": "./src/state/subagentDisplay.ts"
packages/client-runtime/src/state/threadActivityAnnouncement.test.ts
renamed
+1
-1
@@ -13,7 +13,7 @@ import {
13
nextThreadAnnouncement,
14
type ThreadActivitySnapshot,
15
type ThreadAnnouncementMemory,
16
-} from "./threadActivityAnnouncement";
16
+} from "./threadActivityAnnouncement.ts";
17
18
const firstRun = RunId.make("run-1");
19
const secondRun = RunId.make("run-2");