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, 04:45 UTC
| 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 | }); |