The best way to control Claude Code, Codex and more from any computer or phone

main
tsx 188 lines 6.2 KB
Raw
1 import type { ScreenReaderAnnouncements } from "@t3tools/contracts";
2 import { memo, useEffect, useRef } from "react";
3
4 import { useLiveRegion } from "../../hooks/useLiveRegion";
5 import { m } from "../../i18n/messages";
6 import type { TimelineEntry } from "../../session-logic";
7
8 import {
9 nextThreadAnnouncement,
10 type ThreadActivitySnapshot,
11 type ThreadAnnouncementMemory,
12 } from "@t3tools/client-runtime/state/thread-activity-announcement";
13 import {
14 nextTurnDetailAnnouncement,
15 NO_TURN_DETAIL,
16 turnDetail,
17 type TurnDetailMemory,
18 } from "./turnDetailAnnouncement";
19
20 // Long enough for a screen reader to finish a short label before the next one.
21 const ACTIVITY_GAP_MS = 2_000;
22 // A polite region queues what it can't say yet, so steps written while a
23 // message is still being read would all be heard late. They wait this long.
24 const MESSAGE_HOLD_MS_PER_CHARACTER = 50;
25 const MESSAGE_HOLD_MAX_MS = 15_000;
26
27 function holdAfter(text: string) {
28 return Math.min(
29 MESSAGE_HOLD_MAX_MS,
30 Math.max(ACTIVITY_GAP_MS, text.length * MESSAGE_HOLD_MS_PER_CHARACTER),
31 );
32 }
33
34 /** One write, since a second write to a region replaces the first before it is heard. */
35 function asOneAnnouncement(texts: ReadonlyArray<string>) {
36 return texts
37 .map((text, index) => (index === texts.length - 1 || /[.!?:…]$/.test(text) ? text : `${text}.`))
38 .join(" ");
39 }
40
41 /**
42 * The open thread's polite live regions. Status has its own, so "Needs
43 * approval" landing a moment after a message doesn't replace it unheard.
44 */
45 export const ThreadActivityAnnouncer = memo(function ThreadActivityAnnouncer({
46 threadKey,
47 status,
48 requestId,
49 runId,
50 runStatus,
51 detailBehind,
52 level,
53 entries,
54 workspaceRoot,
55 }: ThreadActivitySnapshot & {
56 /** Null while the timeline shows another thread during a switch. */
57 readonly threadKey: string | null;
58 /** See isDetailBehindShell. */
59 readonly detailBehind: boolean;
60 readonly level: ScreenReaderAnnouncements;
61 /** The thread's entries before any are hidden; unread at the "status" level. */
62 readonly entries: ReadonlyArray<TimelineEntry>;
63 readonly workspaceRoot: string | undefined;
64 }) {
65 const { regionRef, announce, clear } = useLiveRegion();
66 const {
67 regionRef: detailRegionRef,
68 announce: announceDetail,
69 clear: clearDetail,
70 } = useLiveRegion();
71 const memoryRef = useRef<{
72 threadKey: string;
73 level: ScreenReaderAnnouncements;
74 memory: ThreadAnnouncementMemory;
75 detail: TurnDetailMemory;
76 } | null>(null);
77 // Messages are written at once; a step waits its turn, and a newer one replaces it.
78 const stepRef = useRef<{
79 quietUntil: number;
80 waiting: { label: string; timer: ReturnType<typeof setTimeout> } | null;
81 }>({ quietUntil: 0, waiting: null });
82
83 // oxlint-disable-next-line t3code/no-unreasoned-state-sync -- writes the turn's status, messages and steps to the aria-live region after commit
84 useEffect(() => {
85 const step = stepRef.current;
86 const write = (text: string, quietMs: number) => {
87 announceDetail(text);
88 step.quietUntil = Date.now() + quietMs;
89 };
90 const takeWaiting = () => {
91 const label = step.waiting?.label ?? null;
92 if (step.waiting !== null) clearTimeout(step.waiting.timer);
93 step.waiting = null;
94 return label;
95 };
96
97 if (threadKey === null) {
98 takeWaiting();
99 memoryRef.current = null;
100 clear();
101 clearDetail();
102 return;
103 }
104 const waitingLabel = takeWaiting();
105 if (detailBehind) {
106 // The dropped step counts as unsaid, so it is read once the detail catches up.
107 if (waitingLabel !== null && memoryRef.current !== null) {
108 const { detail } = memoryRef.current;
109 memoryRef.current = { ...memoryRef.current, detail: { ...detail, activity: null } };
110 }
111 return;
112 }
113 const previous = memoryRef.current?.threadKey === threadKey ? memoryRef.current : null;
114 const turn = nextThreadAnnouncement(
115 previous?.memory ?? null,
116 { status, requestId, runId, runStatus },
117 m,
118 );
119 // A new level starts from what the turn already holds, so raising it mid-turn replays nothing.
120 const previousDetail = previous?.level === level ? previous.detail : null;
121 const detail = nextTurnDetailAnnouncement(previousDetail, {
122 ...(level === "status"
123 ? NO_TURN_DETAIL
124 : turnDetail(entries, workspaceRoot, previousDetail?.tailId ?? null)),
125 level,
126 status,
127 });
128 memoryRef.current = { threadKey, level, memory: turn.memory, detail: detail.memory };
129 if (previous === null) {
130 step.quietUntil = 0;
131 clear();
132 clearDetail();
133 return;
134 }
135 if (detail.messages.length > 0) {
136 // NVDA reads two regions written in the same frame in either order, so a
137 // status that lands with a message is read as its last sentence.
138 const text = asOneAnnouncement(
139 turn.announcement === null ? detail.messages : [...detail.messages, turn.announcement],
140 );
141 write(text, holdAfter(text));
142 } else if (turn.announcement !== null) {
143 announce(turn.announcement);
144 step.quietUntil = Math.max(step.quietUntil, Date.now() + ACTIVITY_GAP_MS);
145 }
146 // A waiting label is stale once its step is over or the level no longer reads steps.
147 const label =
148 level !== "everything" || detail.memory.activity === null
149 ? null
150 : (detail.activity ?? waitingLabel);
151 if (label === null) return;
152 const speakStep = () => {
153 step.waiting = null;
154 write(label, ACTIVITY_GAP_MS);
155 };
156 const wait = step.quietUntil - Date.now();
157 if (wait <= 0) {
158 speakStep();
159 return;
160 }
161 const timer = setTimeout(speakStep, wait);
162 step.waiting = { label, timer };
163 // The next run takes the label over; after an unmount nothing is left to speak it.
164 return () => clearTimeout(timer);
165 }, [
166 threadKey,
167 status,
168 requestId,
169 runId,
170 runStatus,
171 detailBehind,
172 level,
173 entries,
174 workspaceRoot,
175 announce,
176 clear,
177 announceDetail,
178 clearDetail,
179 ]);
180
181 // No role="status": Orca 50 maps it to a status bar in Chromium and drops its updates.
182 return (
183 <>
184 <div ref={detailRegionRef} aria-live="polite" className="sr-only" />
185 <div ref={regionRef} aria-live="polite" className="sr-only" />
186 </>
187 );
188 });