fix(webapp): announce the composer's counter and name the history button

The character counter's live region only entered the DOM at the warning point,
and several screen readers only announce updates for a region that was already
there; it is now always mounted and empty until there is something to say.

The history trigger's aria-label replaced the chat title it shows, so a
speech-input user could not activate it by the words on it. The title now leads
the accessible name.

Author: kathiekiwi

apps/webapp/app/components/dashboard-agent/DashboardAgentComposer.tsx

@@ -2,7 +2,11 @@ import { ArrowUpIcon, StopIcon } from "@heroicons/react/20/solid";
 import { useEffect, useRef } from "react";
 import { Button } from "~/components/primitives/Buttons";
 import { cn } from "~/utils/cn";
-import { MAX_MESSAGE_CHARS, MESSAGE_CHARS_WARN_AT } from "./message-limits";
+import {
+  MAX_MESSAGE_CHARS,
+  MESSAGE_CHARS_WARN_AT,
+  messageCountAnnouncement,
+} from "./message-limits";
 
 export type DashboardAgentComposerLayout = "docked" | "hero";
 
@@ -118,14 +122,19 @@ export function DashboardAgentComposer({
           )}
         </div>
       </div>
+      {/* Mounted from the start, empty until there is something to say: a region that appears
+          with its first message goes unannounced in several screen readers. */}
+      <p className="sr-only" aria-live="polite">
+        {messageCountAnnouncement(value.length)}
+      </p>
       {/* Only near the limit: a normal message never sees a counter. */}
       {value.length >= MESSAGE_CHARS_WARN_AT ? (
         <p
+          aria-hidden
           className={cn(
             "self-end text-xxs tabular-nums",
             value.length >= MAX_MESSAGE_CHARS ? "text-error" : "text-text-dimmed"
           )}
-          aria-live="polite"
         >
           {value.length} / {MAX_MESSAGE_CHARS}
         </p>

apps/webapp/app/components/dashboard-agent/DashboardAgentHeader.tsx

@@ -7,6 +7,7 @@ import { Popover, PopoverArrowTrigger, PopoverContent } from "~/components/primi
 import { ShortcutKey } from "~/components/primitives/ShortcutKey";
 import type { Shortcut } from "~/hooks/useShortcutKeys";
 import { DashboardAgentHistoryMenu, type DashboardAgentChat } from "./DashboardAgentHistory";
+import { chatHistoryTriggerLabel } from "./header-labels";
 
 // Display only. The key is registered once, in `DashboardAgent`; registering it
 // anywhere else makes the keystroke fire twice.
@@ -59,7 +60,7 @@ export function DashboardAgentHeader({
           isOpen={isHistoryOpen}
           overflowHidden
           className="min-w-0"
-          aria-label="Chat history"
+          aria-label={chatHistoryTriggerLabel(title)}
           title={title}
         >
           <span className="truncate text-sm font-medium text-text-bright">{title}</span>

apps/webapp/app/components/dashboard-agent/header-labels.test.ts

@@ -0,0 +1,35 @@
+import { readFileSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+import { chatHistoryTriggerLabel } from "./header-labels";
+
+describe("chatHistoryTriggerLabel", () => {
+  it("starts with the words on the button, so speech input can activate it", () => {
+    const title = "Why did my task retry?";
+    const label = chatHistoryTriggerLabel(title);
+    expect(label.startsWith(title)).toBe(true);
+    expect(label).toContain(title);
+  });
+
+  it("still says what the button does", () => {
+    expect(chatHistoryTriggerLabel("New chat").toLowerCase()).toContain("chat history");
+  });
+
+  it("falls back to the purpose when there is no title to read", () => {
+    expect(chatHistoryTriggerLabel("")).toBe("Chat history");
+    expect(chatHistoryTriggerLabel("   ")).toBe("Chat history");
+  });
+});
+
+/**
+ * Structural guard, not behavioural proof: the webapp has no DOM test environment, so nothing
+ * here computes a real accessible name. It asserts the header asks for the label above rather
+ * than a constant that would replace the visible title.
+ */
+describe("the header's history trigger", () => {
+  const source = readFileSync(new URL("./DashboardAgentHeader.tsx", import.meta.url), "utf8");
+
+  it("names itself with the title, not with a bare constant", () => {
+    expect(source).toContain("aria-label={chatHistoryTriggerLabel(title)}");
+    expect(source).not.toContain('aria-label="Chat history"');
+  });
+});

apps/webapp/app/components/dashboard-agent/header-labels.ts

@@ -0,0 +1,9 @@
+/**
+ * The chat-history trigger shows the chat's title and opens the history menu, so its accessible
+ * name has to carry both: speech-input users activate a control by the words they can see, and a
+ * bare "Chat history" hides them (WCAG 2.5.3). The title leads, because that is what is read.
+ */
+export function chatHistoryTriggerLabel(title: string): string {
+  const trimmed = title.trim();
+  return trimmed ? `${trimmed}, chat history` : "Chat history";
+}

apps/webapp/app/components/dashboard-agent/message-limits.test.ts

@@ -1,3 +1,4 @@
+import { readFileSync } from "node:fs";
 import { describe, expect, it } from "vitest";
 import {
   checkMessageParts,
@@ -6,6 +7,8 @@ import {
   MAX_MESSAGE_BODY_BYTES,
   MAX_MESSAGE_CHARS,
   MAX_MESSAGE_PARTS,
+  MESSAGE_CHARS_WARN_AT,
+  messageCountAnnouncement,
 } from "./message-limits";
 
 describe("message limits", () => {
@@ -61,3 +64,39 @@ describe("message limits", () => {
     expect(exceedsMessageBodyBytes(null)).toBe(false);
   });
 });
+
+describe("messageCountAnnouncement", () => {
+  it("says nothing at all for a normal message", () => {
+    expect(messageCountAnnouncement(0)).toBe("");
+    expect(messageCountAnnouncement(MESSAGE_CHARS_WARN_AT - 1)).toBe("");
+  });
+
+  it("reads the count out from the warning point on", () => {
+    expect(messageCountAnnouncement(MESSAGE_CHARS_WARN_AT)).toBe(
+      `${MESSAGE_CHARS_WARN_AT} / ${MAX_MESSAGE_CHARS}`
+    );
+    expect(messageCountAnnouncement(MAX_MESSAGE_CHARS)).toBe(
+      `${MAX_MESSAGE_CHARS} / ${MAX_MESSAGE_CHARS}`
+    );
+  });
+});
+
+/**
+ * Structural guard, not behavioural proof: the webapp has no DOM test environment, so nothing
+ * here mounts the composer or listens to a screen reader. It asserts the live region is written
+ * unconditionally, which is the part the announcement depends on.
+ */
+describe("the composer's live region", () => {
+  const source = readFileSync(new URL("./DashboardAgentComposer.tsx", import.meta.url), "utf8");
+
+  it("is in the DOM before the count reaches the warning point", () => {
+    const region = source.slice(source.indexOf('aria-live="polite"'));
+    expect(region).toContain("messageCountAnnouncement(value.length)");
+    // The old form: the region itself only existed past the threshold.
+    expect(source).not.toMatch(/MESSAGE_CHARS_WARN_AT \? \(\s*<p[^>]*aria-live/);
+  });
+
+  it("does not read the visible counter out a second time", () => {
+    expect(source).toContain("aria-hidden");
+  });
+});

apps/webapp/app/components/dashboard-agent/message-limits.ts

@@ -10,6 +10,15 @@ export const MAX_MESSAGE_CHARS = 8_000;
 /** The counter only shows near the limit, so a normal message never sees it. */
 export const MESSAGE_CHARS_WARN_AT = Math.floor(MAX_MESSAGE_CHARS * 0.9);
 
+/**
+ * What the composer's live region says at this length: empty until the counter is worth
+ * showing. The region itself stays mounted whatever this returns — several screen readers only
+ * announce changes to a region that was already in the DOM.
+ */
+export function messageCountAnnouncement(length: number): string {
+  return length >= MESSAGE_CHARS_WARN_AT ? `${length} / ${MAX_MESSAGE_CHARS}` : "";
+}
+
 /** A composed message is a handful of parts; dozens means something is wrong. */
 export const MAX_MESSAGE_PARTS = 20;