Skip to content

Commit 93cd221

Browse files
Leos-Khaiclaude
andcommitted
fix(a11y): announce unseen turns from other devices and repeated messages
A turn started from another device can start and finish between two renders while this client is idle, and its outcome was never spoken. Any finished turn newer than the last one seen now counts; with no earlier turn to compare, work must have been under way so loading history stays silent. On web, two identical announcements in a row, such as two approvals, could be skipped by screen readers that ignore a swap to the same text. The status region now empties first and fills a moment later. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
1 parent 323d97f commit 93cd221

3 files changed

Lines changed: 29 additions & 14 deletions

File tree

‎apps/web/src/components/chat/ChatActivityAnnouncer.tsx‎

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,10 @@ export function ChatActivityAnnouncer(props: ActivityAnnouncementState) {
2020
userInputRequestId,
2121
} = props;
2222
const previousRef = useRef<ActivityAnnouncementState | null>(null);
23-
const [announcement, setAnnouncement] = useState<{ message: string; id: number } | null>(null);
23+
const restoreTimerRef = useRef<number | undefined>(undefined);
24+
const [announcement, setAnnouncement] = useState<string | null>(null);
25+
26+
useEffect(() => () => window.clearTimeout(restoreTimerRef.current), []);
2427

2528
useEffect(() => {
2629
const next = {
@@ -37,9 +40,14 @@ export function ChatActivityAnnouncer(props: ActivityAnnouncementState) {
3740
const messages = activityAnnouncementMessages(previous, next);
3841
if (messages.length > 0) {
3942
const message = messages.join(". ");
40-
setAnnouncement((current) => ({ message, id: (current?.id ?? 0) + 1 }));
43+
// Empty the region first and fill it a moment later. Screen readers can
44+
// ignore a swap to identical text, such as two approvals in a row.
45+
window.clearTimeout(restoreTimerRef.current);
46+
setAnnouncement(null);
47+
restoreTimerRef.current = window.setTimeout(() => setAnnouncement(message), 100);
4148
} else if (previous !== null && previous.threadKey !== threadKey) {
4249
// Drop the last thread's message so it can't be read out on this one.
50+
window.clearTimeout(restoreTimerRef.current);
4351
setAnnouncement(null);
4452
}
4553
}, [
@@ -54,9 +62,7 @@ export function ChatActivityAnnouncer(props: ActivityAnnouncementState) {
5462

5563
return (
5664
<div role="status" aria-atomic="true" className="sr-only">
57-
{/* A fresh node per announcement makes screen readers repeat identical
58-
text, such as two approvals in a row. */}
59-
{announcement ? <span key={announcement.id}>{announcement.message}</span> : null}
65+
{announcement}
6066
</div>
6167
);
6268
}

‎packages/client-runtime/src/activityAnnouncement.test.ts‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -46,8 +46,15 @@ describe("activityAnnouncementMessages", () => {
4646
});
4747

4848
it("announces a turn that finished before its running state was seen", () => {
49-
const sending = { ...idle, working: true };
50-
expect(activityAnnouncementMessages(sending, { ...running, turnState: "completed" })).toEqual([
49+
const finished = { ...running, working: false, turnState: "completed" as const };
50+
expect(activityAnnouncementMessages({ ...idle, working: true }, finished)).toEqual([
51+
"Response complete",
52+
]);
53+
// Started from another device while this client was idle.
54+
expect(activityAnnouncementMessages(idle, finished)).toEqual(["Response complete"]);
55+
// The thread's first turn, sent from this client.
56+
const empty = { ...idle, turnId: null, turnState: null, turnRequestedAt: null };
57+
expect(activityAnnouncementMessages({ ...empty, working: true }, finished)).toEqual([
5158
"Response complete",
5259
]);
5360
});

‎packages/client-runtime/src/activityAnnouncement.ts‎

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -30,14 +30,16 @@ function endedTurnState(previous: ActivityAnnouncementState, next: ActivityAnnou
3030
if (next.turnId === previous.turnId) {
3131
return previous.turnState === "running" ? next.turnState : null;
3232
}
33-
// A short turn can start and finish between two renders, so its running
34-
// state is never seen. Count it only while work was already under way and
35-
// the turn is newer than the last one, so loading history or reverting to
36-
// an older turn stays silent.
33+
// A short turn, or one started from another device, can start and finish
34+
// between two renders, so its running state is never seen. Count it when it
35+
// is newer than the last turn seen, so reverting to an older turn stays
36+
// silent. With no earlier turn to compare, only count it if work was under
37+
// way, so loading the thread's history stays silent.
3738
const newer =
38-
previous.turnRequestedAt === null ||
39-
(next.turnRequestedAt !== null && next.turnRequestedAt > previous.turnRequestedAt);
40-
return previous.working && newer ? next.turnState : null;
39+
previous.turnRequestedAt === null
40+
? previous.working
41+
: next.turnRequestedAt !== null && next.turnRequestedAt > previous.turnRequestedAt;
42+
return newer ? next.turnState : null;
4143
}
4244

4345
/**

0 commit comments

Comments
 (0)