The best way to control Claude Code, Codex and more from any computer or phone
fix(web): screen reader announcements no longer linger after they stop applying (#31676)
Julius Marminge committed
Nov 16, 2026 at 12:51 UTC
959f422d457bc7c5845cb531996da7a398dd95a3
4 files changed
+50
-15
apps/web/src/components/chat/OpenInPicker.browser.test.tsx
+1
-1
@@ -232,7 +232,7 @@ describe("open in editor announcement", () => {
232
using _timers = fakeTimers();
233
const regions = () => [...document.querySelectorAll('body > [aria-live="polite"]')];
234
const spoken = async () => {
235
- await act(async () => vi.runAllTimers());
235
+ await act(async () => vi.advanceTimersByTime(250));
236
return regions()
237
.map((region) => region.textContent)
238
.join("");
apps/web/src/hooks/useLiveRegion.ts
+2
-5
@@ -1,9 +1,6 @@
1
import { useState } from "react";
2
3
-// NVDA reads a polite region's leftover text again when focus returns from a
4
-// dialog, so an announcement is cleared once it has had time to be spoken.
5
-// Clearing doesn't cut off speech that already started.
6
-const CLEAR_AFTER_MS = 7_000;
3
+import { CLEAR_SPOKEN_AFTER_MS } from "../lib/announce";
4
5
/**
6
* A polite live region written straight to the DOM, so speaking never
@@ -30,7 +27,7 @@ export function createLiveRegion() {
27
// Screen readers ignore a write that leaves the text unchanged, so a repeat
28
// gets a trailing non-breaking space to count as new.
29
region.textContent = region.textContent === text ? `${text}\u00A0` : text;
33
- clearTimer = setTimeout(clear, CLEAR_AFTER_MS);
30
+ clearTimer = setTimeout(clear, CLEAR_SPOKEN_AFTER_MS);
31
};
32
33
const attach = (node: HTMLElement | null) => {
apps/web/src/lib/announce.browser.test.ts
+27
-4
@@ -33,10 +33,10 @@ describe("announce", () => {
33
Array.from(document.querySelectorAll('[aria-live="polite"]'), (region) => region.textContent);
34
35
announce("Claude");
36
- vi.runAllTimers();
36
+ vi.advanceTimersByTime(250);
37
const first = regionTexts();
38
announce("Claude");
39
- vi.runAllTimers();
39
+ vi.advanceTimersByTime(250);
40
41
expect(regionTexts()).toEqual([...first].reverse());
42
expect(regionTexts()).toContain("Claude");
@@ -48,15 +48,38 @@ describe("announce", () => {
48
announce("Settled 1 thread, Ctrl+Z to undo", "undo");
49
announce("Opening in VS Code");
50
announce("Settled 2 threads, Ctrl+Z to undo", "undo");
51
- vi.runAllTimers();
51
+ vi.advanceTimersByTime(250);
52
53
expect(spokenText()).toEqual(["Opening in VS Code. Settled 2 threads, Ctrl+Z to undo"]);
54
55
announce("Settled 1 thread, Ctrl+Z to undo", "undo");
56
announce("Opening in Zed");
57
cancelAnnouncement("undo");
58
- vi.runAllTimers();
58
+ vi.advanceTimersByTime(250);
59
60
expect(spokenText()).toEqual(["Opening in Zed"]);
61
});
62
+
63
+ it("removes a spoken message from the page once it has had time to be read", () => {
64
+ using _timers = fakeTimers();
65
+
66
+ announce("Model: Claude Sonnet 5.5");
67
+ vi.advanceTimersByTime(250);
68
+ expect(spokenText()).toEqual(["Model: Claude Sonnet 5.5"]);
69
+
70
+ vi.advanceTimersByTime(60_000);
71
+ expect(spokenText()).toEqual([]);
72
+ });
73
+
74
+ it("removes a spoken message from the page when its source cancels it", () => {
75
+ using _timers = fakeTimers();
76
+
77
+ announce("Settled 1 thread, Ctrl+Z to undo", "thread-undo-notice");
78
+ vi.advanceTimersByTime(250);
79
+ expect(spokenText()).toEqual(["Settled 1 thread, Ctrl+Z to undo"]);
80
+
81
+ vi.advanceTimersByTime(4_750);
82
+ cancelAnnouncement("thread-undo-notice");
83
+ expect(spokenText()).toEqual([]);
84
+ });
85
});
apps/web/src/lib/announce.ts
+20
-5
@@ -3,24 +3,38 @@
3
// messages wait until focus has stayed put for a moment, then are spoken together.
4
const FOCUS_SETTLE_MS = 250;
5
6
+// NVDA reads a polite region's leftover text again when focus returns from a
7
+// dialog, so an announcement is cleared once it has had time to be spoken.
8
+// Clearing doesn't cut off speech that already started.
9
+export const CLEAR_SPOKEN_AFTER_MS = 7_000;
10
+
11
let regions: readonly [HTMLElement, HTMLElement] | null = null;
12
let pending: { message: string; source: string | undefined }[] = [];
13
+let spokenSources: (string | undefined)[] = [];
14
let flushTimer: ReturnType<typeof setTimeout> | undefined;
15
+let clearTimer: ReturnType<typeof setTimeout> | undefined;
16
17
function scheduleFlush() {
18
clearTimeout(flushTimer);
19
flushTimer = setTimeout(flush, FOCUS_SETTLE_MS);
20
}
21
22
+function clearSpoken() {
23
+ clearTimeout(clearTimer);
24
+ spokenSources = [];
25
+ for (const region of regions ?? []) region.textContent = "";
26
+}
27
+
28
function flush() {
29
if (!regions || pending.length === 0) return;
17
- const [first, second] = regions;
30
+ clearSpoken();
31
// Alternating between two regions lets the same message be spoken twice in a row.
19
- const target = first.textContent ? second : first;
20
- first.textContent = "";
21
- second.textContent = "";
32
+ const [target, other] = regions;
33
+ regions = [other, target];
34
target.textContent = pending.map((entry) => entry.message).join(". ");
35
+ spokenSources = pending.map((entry) => entry.source);
36
pending = [];
37
+ clearTimer = setTimeout(clearSpoken, CLEAR_SPOKEN_AFTER_MS);
38
}
39
40
function createRegion() {
@@ -50,7 +64,8 @@ export function announce(message: string, source?: string) {
64
scheduleFlush();
65
}
66
53
-/** Drops a message from `source` that hasn't been spoken yet, once it no longer applies. */
67
+/** Drops a message from `source`, waiting or already spoken, once it no longer applies. */
68
export function cancelAnnouncement(source: string) {
69
pending = pending.filter((entry) => entry.source !== source);
70
+ if (spokenSources.includes(source)) clearSpoken();
71
}