@stigmer/react 3.1.2 → 3.1.3

package/src/session/__tests__/PlanEditor.test.tsx

@@ -81,9 +81,9 @@ describe("PlanEditor", () => {
     renderEditor({ onBuildFromPlan });
 
     await waitFor(() =>
-      expect(screen.getByText("Build from plan")).toBeTruthy(),
+      expect(screen.getByText("Build")).toBeTruthy(),
     );
-    fireEvent.click(screen.getByText("Build from plan"));
+    fireEvent.click(screen.getByText("Build"));
     expect(onBuildFromPlan).toHaveBeenCalledTimes(1);
   });
 
@@ -99,7 +99,7 @@ describe("PlanEditor", () => {
     );
     expect(screen.getByText("Rollout Plan").className).toContain("truncate");
 
-    const buildLabel = screen.getByText("Build from plan");
+    const buildLabel = screen.getByText("Build");
     expect(buildLabel.className).toContain("truncate");
     const toolbar = screen.getByRole("tablist", { name: "Plan view" })
       .parentElement!;
@@ -188,7 +188,7 @@ describe("PlanEditor — read-only (superseded plan)", () => {
     );
     expect(screen.getByText("Superseded by a newer plan")).toBeTruthy();
     expect(screen.queryByText("Edit")).toBeNull();
-    expect(screen.queryByText("Build from plan")).toBeNull();
+    expect(screen.queryByText("Build")).toBeNull();
   });
 
   it("never applies the current plan's draft to a superseded plan", async () => {

package/src/session/__tests__/PlanStreamingDocument.test.tsx

@@ -44,7 +44,7 @@ describe("PlanStreamingDocument — live plan tab view", () => {
     render(<PlanStreamingDocument displayText={"# Live Plan\n\nBody"} />);
 
     expect(screen.queryByText("Edit")).toBeNull();
-    expect(screen.queryByText("Build from plan")).toBeNull();
+    expect(screen.queryByText("Build")).toBeNull();
     expect(screen.queryByRole("tablist")).toBeNull();
   });
 });

package/src/session/__tests__/SessionViewer-fileReviewDock.test.tsx

@@ -3,6 +3,8 @@ import { render, screen, cleanup, fireEvent } from "@testing-library/react";
 import { create } from "@bufbuild/protobuf";
 import {
   CapturedFileChangeSchema,
+  FileChangeProgressSchema,
+  FileChangeProgressEntrySchema,
   FileChangeSetSchema,
 } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/filereview_pb";
 import { FileContentSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
@@ -70,6 +72,31 @@ function pendingChangeSet(id: string) {
   });
 }
 
+function progressSnapshot() {
+  return create(FileChangeProgressSchema, {
+    changeSetId: "cs-1",
+    filesChanged: 2,
+    linesAdded: 4,
+    linesRemoved: 1,
+    entries: [
+      create(FileChangeProgressEntrySchema, {
+        pathAfter: "a.ts",
+        kind: FileChangeKind.ADD,
+        linesAdded: 4,
+        linesRemoved: 0,
+      }),
+      create(FileChangeProgressEntrySchema, {
+        pathBefore: "b.ts",
+        pathAfter: "b.ts",
+        kind: FileChangeKind.MODIFY,
+        linesAdded: 0,
+        linesRemoved: 1,
+      }),
+    ],
+    capturedAt: "2026-07-05T00:00:00Z",
+  });
+}
+
 const stubConv = {
   session: { spec: {} },
   isLoading: false,
@@ -92,6 +119,7 @@ const stubConv = {
   submitApproval: vi.fn(),
   submittingApprovalIds: new Set<string>(),
   fileChangeSets: [] as ReturnType<typeof pendingChangeSet>[],
+  fileChangeProgress: undefined as ReturnType<typeof progressSnapshot> | undefined,
   submitFileDecision: vi.fn(),
   submittingFileDecisionKeys: new Set<string>(),
   fileDecisionErrors: new Map<string, Error>(),
@@ -144,6 +172,7 @@ import { SessionViewer } from "../SessionViewer";
 beforeEach(() => {
   threadProps.length = 0;
   stubConv.fileChangeSets = [];
+  stubConv.fileChangeProgress = undefined;
   stubConv.submitFileDecision = vi.fn();
 });
 
@@ -189,6 +218,34 @@ describe("SessionViewer — file-review dock wiring", () => {
     );
   });
 
+  it("renders no progress bar when no turn is capturing", () => {
+    render(<SessionViewer sessionId="ses_1" org="acme" />);
+    expect(
+      document.querySelector('[data-cursor-target="file-change-progress-bar"]'),
+    ).toBeNull();
+  });
+
+  it("shows the mid-run progress strip above the composer while a turn is capturing", () => {
+    // Progress is present (CAPTURING) and the dock is empty — the two are
+    // mutually exclusive per turn, so the strip stands in for the dock.
+    stubConv.fileChangeProgress = progressSnapshot();
+    render(<SessionViewer sessionId="ses_1" org="acme" />);
+
+    const bar = document.querySelector('[data-cursor-target="file-change-progress-bar"]');
+    expect(bar).toBeTruthy();
+    expect(screen.getByText(/2 files changing/)).toBeTruthy();
+    expect(
+      document.querySelector('[data-cursor-target="file-review-dock"]'),
+    ).toBeNull();
+
+    // Pinned in the fixed strip, ordered before the composer input.
+    const composer = screen.getByTestId("composer-probe");
+    expect(bar!.parentElement).toBe(composer.parentElement);
+    expect(
+      bar!.compareDocumentPosition(composer) & Node.DOCUMENT_POSITION_FOLLOWING,
+    ).toBeTruthy();
+  });
+
   it("gives the thread records-only file-review props (no decision callbacks)", () => {
     render(<SessionViewer sessionId="ses_1" org="acme" />);
 

package/src/session/__tests__/useSessionConversation.test.tsx

@@ -312,6 +312,50 @@ describe("useSessionConversation", () => {
     });
   });
 
+  it("sets NO optimistic pendingUserMessage for a buildFromPlan send (the thread hides the turn)", async () => {
+    methods.listBySession.mockResolvedValue({ entries: [] });
+    const newExec = makeExecution("new-exec", ExecutionPhase.EXECUTION_PENDING);
+    newExec.metadata!.id = "new-exec";
+    methods.executionCreate.mockResolvedValue(newExec);
+
+    const { result } = renderHook(
+      () => useSessionConversation("session-1", "org"),
+      { wrapper: createWrapper(mockStigmer) },
+    );
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    await act(async () => {
+      await result.current.sendFollowUp("Build from plan", {
+        buildFromPlan: true,
+      });
+    });
+
+    expect(result.current.pendingUserMessage).toBeNull();
+    expect(methods.executionCreate).toHaveBeenCalledWith(
+      expect.objectContaining({ message: "Build from plan" }),
+    );
+  });
+
+  it("sets pendingUserMessage when a buildFromPlan send FAILS (failure must be visible)", async () => {
+    methods.listBySession.mockResolvedValue({ entries: [] });
+    methods.executionCreate.mockRejectedValue(new Error("create boom"));
+
+    const { result } = renderHook(
+      () => useSessionConversation("session-1", "org"),
+      { wrapper: createWrapper(mockStigmer) },
+    );
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    await act(async () => {
+      await result.current.sendFollowUp("Build from plan", {
+        buildFromPlan: true,
+      });
+    });
+
+    expect(result.current.sendError?.message).toBe("create boom");
+    expect(result.current.pendingUserMessage).toBe("Build from plan");
+  });
+
   it("preserves the message and surfaces sendError when the send fails", async () => {
     methods.listBySession.mockResolvedValue({ entries: [] });
     methods.executionCreate.mockRejectedValue(new Error("create boom"));

package/src/session/facets/__tests__/ArtifactsTab.test.tsx

@@ -61,32 +61,32 @@ function openPreviewFor(name: string) {
 
 afterEach(cleanup);
 
-describe("ArtifactsTab — plan 'Build from plan' wiring", () => {
-  it("shows 'Build from plan' in the preview of a plan.md artifact", () => {
+describe("ArtifactsTab — plan 'Build' wiring", () => {
+  it("shows 'Build' in the preview of a plan.md artifact", () => {
     renderTab(vi.fn());
 
     openPreviewFor("plan.md");
 
     const dialog = document.querySelector("dialog")!;
-    expect(within(dialog).getByText("Build from plan")).toBeTruthy();
+    expect(within(dialog).getByText("Build")).toBeTruthy();
   });
 
-  it("does not show 'Build from plan' in the preview of a non-plan artifact", () => {
+  it("does not show 'Build' in the preview of a non-plan artifact", () => {
     renderTab(vi.fn());
 
     openPreviewFor("notes.md");
 
     const dialog = document.querySelector("dialog")!;
-    expect(within(dialog).queryByText("Build from plan")).toBeNull();
+    expect(within(dialog).queryByText("Build")).toBeNull();
   });
 
-  it("invokes onImplementPlan when 'Build from plan' is clicked for a plan", () => {
+  it("invokes onImplementPlan when 'Build' is clicked for a plan", () => {
     const onImplementPlan = vi.fn();
     renderTab(onImplementPlan);
 
     openPreviewFor("plan.md");
     const dialog = document.querySelector("dialog")!;
-    fireEvent.click(within(dialog).getByText("Build from plan"));
+    fireEvent.click(within(dialog).getByText("Build"));
 
     expect(onImplementPlan).toHaveBeenCalledTimes(1);
   });

package/src/session/plan-document.ts

@@ -6,7 +6,6 @@
 // their module graph (DD-003 headless-first).
 
 import { virtualEntryId } from "../internal/store/index.js";
-import { PLAN_ARTIFACT_NAME } from "../library/detect-plan-artifact.js";
 
 /**
  * Virtual entry id of the plan document tab. One tab per session — the host
@@ -15,5 +14,17 @@ import { PLAN_ARTIFACT_NAME } from "../library/detect-plan-artifact.js";
  */
 export const PLAN_DOCUMENT_ENTRY_ID = virtualEntryId("plan");
 
-/** The plan tab's path — doubles as its tab label, matching the artifact name. */
-export const PLAN_DOCUMENT_PATH = PLAN_ARTIFACT_NAME;
+/**
+ * The plan tab's path — doubles as its tab label.
+ *
+ * Deliberately plan-AGNOSTIC ("Plan"), not the artifact's filename. The
+ * workspace surface identifies a virtual document's tab by
+ * `editorKey(entryId, path)`, so `path` is part of the tab's IDENTITY — and the
+ * session keeps exactly ONE plan tab that swaps which plan it shows (latest
+ * editable, or a superseded plan read-only). Now that plans carry unique,
+ * title-derived filenames (`<slug>_<id>.plan.md`), binding this label to any one
+ * plan's name would mint a new tab identity per plan and shatter the
+ * single-tab design. A stable, generic label is therefore required, not a
+ * stylistic choice — do not "fix" it to track the filename.
+ */
+export const PLAN_DOCUMENT_PATH = "Plan";

package/src/session/usePlanDraft.ts

@@ -32,7 +32,7 @@ export interface PlanDraftController {
   /**
    * Snapshot reader for submit-time consumers: returns the current draft (or
    * `null`) without the caller depending on draft state. Referentially stable
-   * for the lifetime of the component (DD-010) — "Build from plan" reads the
+   * for the lifetime of the component (DD-010) — the "Build" action reads the
    * draft through this at click time, so per-keystroke draft updates never
    * re-bind the build callback or re-render the conversation column.
    */

package/src/session/useSessionConversation.ts

@@ -3,7 +3,7 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
 import type { PendingApproval } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/approval_pb";
-import type { FileChangeSet } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/filereview_pb";
+import type { FileChangeProgress, FileChangeSet } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/filereview_pb";
 import { ApprovalAction, ExecutionPhase, FileChangeSetStatus, FileDecisionAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import type { Session } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
 import type { McpServerUsage as ProtoMcpServerUsage } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
@@ -97,7 +97,7 @@ export interface SendFollowUpOptions {
    */
   readonly interactionMode?: "agent" | "plan";
   /**
-   * Marks this execution as a "Build from plan" turn.
+   * Marks this execution as a Build-from-plan turn.
    *
    * @see {@link CreateAgentExecutionInput.buildFromPlan}
    */
@@ -222,6 +222,13 @@ export interface UseSessionConversationReturn {
 
   /** Captured change sets awaiting file review on the active execution, empty when none. */
   readonly fileChangeSets: readonly FileChangeSet[];
+  /**
+   * Mid-run live capture (DD-32): the transient, non-authoritative snapshot of the
+   * workspace delta accumulating during the active turn ("N files changed so far").
+   * Undefined when no turn is currently capturing. Never decidable — the reviewed
+   * diff is {@link fileChangeSets}.
+   */
+  readonly fileChangeProgress: FileChangeProgress | undefined;
   /** Submit a file-review decision for a change set. The executionId is managed internally. */
   readonly submitFileDecision: (
     changeSetId: string,
@@ -554,7 +561,14 @@ export function useSessionConversation(
       // Capture for retry and clear any prior failure before the new attempt.
       lastSendRef.current = { message, options };
       setSendError(null);
-      setPendingUserMessage(message);
+      // A Build-from-plan turn shows no optimistic bubble: its message is a
+      // machine-written label, not user prose, and the thread hides the turn
+      // entirely (the plan card's "Starting build…" state covers the send
+      // window). It is still set on FAILURE below, so a failed build send
+      // renders the failed-with-retry bubble instead of vanishing.
+      if (!options?.buildFromPlan) {
+        setPendingUserMessage(message);
+      }
 
       try {
         const needsSessionUpdate =
@@ -596,7 +610,10 @@ export function useSessionConversation(
       } catch (err) {
         // Surface the failure and KEEP the user's message visible (do not clear
         // pendingUserMessage) so the turn renders as failed-with-retry instead
-        // of vanishing. Covers both the update() and create() paths.
+        // of vanishing. Covers both the update() and create() paths. For a
+        // build turn this is the FIRST time the message is set — failure is
+        // the one case where its label must become visible.
+        setPendingUserMessage(message);
         setSendError(toError(err));
         if (process.env.NODE_ENV !== "production") {
           console.error("[useSessionConversation] sendFollowUp failed:", err);
@@ -641,6 +658,16 @@ export function useSessionConversation(
     [activeStreamExecution],
   );
 
+  // Mid-run live capture (DD-32): the transient, non-authoritative "N files
+  // changed so far" snapshot for the active turn. The server clears it once the
+  // turn's change set leaves CAPTURING, so its mere presence means a turn is
+  // still accumulating changes. Reference-stable per DD-010 (it rides the
+  // structurally-shared live status).
+  const fileChangeProgress = useMemo<FileChangeProgress | undefined>(
+    () => activeStreamExecution?.status?.fileChangeProgress,
+    [activeStreamExecution],
+  );
+
   const submitFileDecision = useCallback(
     async (
       changeSetId: string,
@@ -685,6 +712,7 @@ export function useSessionConversation(
     clearApprovalError,
 
     fileChangeSets,
+    fileChangeProgress,
     submitFileDecision,
     submittingFileDecisionKeys: submittingDecisionKeys,
     fileDecisionErrors,

package/src/workspace/EditorTabs.tsx

@@ -4,6 +4,17 @@ import { useCallback, type KeyboardEvent, type MouseEvent } from "react";
 import { cn } from "@stigmer/theme";
 import { editorKey, type OpenEditor } from "../internal/store/index.js";
 
+/**
+ * Deterministic, space-free DOM id for a tab, built from an instance-scoped
+ * `prefix` (a `useId()` value) and the editor `key`. Shared by the tab (its
+ * `id`) and the editor body (its `aria-labelledby`) so the two associate; the
+ * key is percent-encoded because editor keys embed file paths that may contain
+ * characters (spaces) illegal in a space-separated IDREF.
+ */
+export function editorTabDomId(prefix: string, key: string): string {
+  return `${prefix}${encodeURIComponent(key)}`;
+}
+
 /** Props for {@link EditorTabs}. */
 export interface EditorTabsProps {
   /** Open editors in tab order. */
@@ -16,6 +27,14 @@ export interface EditorTabsProps {
   readonly onPin: (entryId: string, path: string) => void;
   /** Close an editor (close button or middle click). */
   readonly onClose: (entryId: string, path: string) => void;
+  /**
+   * DOM id of the editor body (`role="tabpanel"`). When provided together with
+   * {@link tabIdPrefix}, each tab gets a stable `id` and `aria-controls` linking
+   * it to that panel. Optional so the strip degrades gracefully without a panel.
+   */
+  readonly panelId?: string;
+  /** Instance-scoped prefix for per-tab ids (see {@link editorTabDomId}). */
+  readonly tabIdPrefix?: string;
   /** Additional CSS classes for the root element. */
   readonly className?: string;
 }
@@ -28,8 +47,10 @@ export interface EditorTabsProps {
  *
  * A `role="tablist"` of `role="tab"` items; the matching `tabpanel` is the
  * editor body rendered by the surface. Arrow keys move focus between tabs and
- * activate; the per-tab close button is a nested control. All visual properties
- * flow through `--stgm-*` tokens (DD-005).
+ * activate; Delete/Backspace closes the focused tab. The visual close "X" is a
+ * presentational (`aria-hidden`) mouse affordance — assistive tech closes via
+ * the keyboard, so the X is not a nested interactive control (WCAG 4.1.2). All
+ * visual properties flow through `--stgm-*` tokens (DD-005).
  */
 export function EditorTabs({
   editors,
@@ -37,6 +58,8 @@ export function EditorTabs({
   onActivate,
   onPin,
   onClose,
+  panelId,
+  tabIdPrefix,
   className,
 }: EditorTabsProps) {
   const move = useCallback(
@@ -94,7 +117,9 @@ export function EditorTabs({
           <div
             key={key}
             role="tab"
+            id={tabIdPrefix ? editorTabDomId(tabIdPrefix, key) : undefined}
             aria-selected={isActive}
+            aria-controls={panelId}
             tabIndex={isActive ? 0 : -1}
             title={editor.path}
             onClick={() => onActivate(editor.entryId, editor.path)}
@@ -112,22 +137,26 @@ export function EditorTabs({
             <span className={cn("truncate", editor.preview && "italic")}>
               {basename}
             </span>
-            <button
-              type="button"
+            {/* The visual close "X" is a presentational mouse affordance, NOT a
+                nested interactive control: a `<button>` inside `role="tab"` would
+                violate WCAG 4.1.2 (axe `nested-interactive`). Assistive tech and
+                keyboard users close the focused tab via Delete/Backspace (handled
+                above), so `aria-hidden` here removes the redundant nested control
+                without losing the close action for anyone. */}
+            <span
+              aria-hidden="true"
+              title={`Close ${basename}`}
               onClick={(e) => {
                 e.stopPropagation();
                 onClose(editor.entryId, editor.path);
               }}
-              aria-label={`Close ${basename}`}
-              tabIndex={-1}
               className={cn(
-                "shrink-0 rounded p-0.5 text-muted-foreground transition-opacity hover:bg-accent-hover hover:text-foreground",
-                "focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring",
+                "shrink-0 cursor-pointer rounded p-0.5 text-muted-foreground transition-opacity hover:bg-accent-hover hover:text-foreground",
                 isActive ? "opacity-100" : "opacity-0 group-hover:opacity-100",
               )}
             >
               <CloseIcon />
-            </button>
+            </span>
           </div>
         );
       })}

package/src/workspace/ExplorerTree.tsx

@@ -101,7 +101,10 @@ function ExplorerRoot({
           )}
           title={entry.type === "local" ? entry.localPath : entry.gitUrl}
         >
-          <span className="text-[10px] text-muted-foreground-subtle">
+          <span
+            aria-hidden="true"
+            className="text-[10px] text-muted-foreground-subtle"
+          >
             {expanded ? "▼" : "▶"}
           </span>
           <span className="truncate">{entry.name}</span>
@@ -167,6 +170,10 @@ function ExplorerRootBody({
   if (isLoading) {
     return (
       <div
+        // role="status" both announces the loading state to assistive tech and
+        // makes aria-label permitted here (a role-less generic div cannot carry
+        // an accessible name — axe `aria-prohibited-attr`).
+        role="status"
         className="space-y-1.5 px-2 py-2"
         aria-busy="true"
         aria-label={`Loading files for ${entryName}`}
@@ -190,7 +197,7 @@ function ExplorerRootBody({
         <button
           type="button"
           onClick={onRetry}
-          className="ml-2 underline transition-colors hover:text-destructive"
+          className="ml-2 rounded-sm underline transition-colors hover:text-destructive focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
         >
           Retry
         </button>
@@ -226,8 +233,7 @@ function ExplorerRootBody({
       </nav>
       {truncated && (
         <p className="px-3 py-1.5 text-[0.65rem] text-muted-foreground">
-          Showing a partial listing — this repository has too many files to load
-          in full.
+          Showing a partial listing — too many files to load in full.
         </p>
       )}
     </>

package/src/workspace/FileViewer.tsx

@@ -5,6 +5,7 @@ import {
   useCallback,
   useEffect,
   useImperativeHandle,
+  useRef,
   useState,
   type KeyboardEvent,
 } from "react";
@@ -194,7 +195,10 @@ export const FileViewer = forwardRef<FileViewerHandle, FileViewerProps>(
     <div
       role="region"
       aria-label="File viewer"
-      className={cn("flex h-full flex-col", className)}
+      // Focusable (programmatically / on click) so the Escape-to-close handler
+      // fires even when the read-only body holds no natively focusable element.
+      tabIndex={-1}
+      className={cn("flex h-full flex-col focus:outline-none", className)}
       onKeyDown={handleKeyDown}
     >
       {showHeader && (
@@ -260,17 +264,26 @@ function ViewerModeToggle({
     { value: "file", label: "File" },
   ];
 
+  // Selection follows focus, matching ActivityRail / SearchModeToggle.
+  const buttonRefs = useRef<(HTMLButtonElement | null)[]>([]);
+  const selectValue = useCallback(
+    (next: "diff" | "file") => {
+      onChange(next);
+      buttonRefs.current[next === "diff" ? 0 : 1]?.focus();
+    },
+    [onChange],
+  );
   const handleKeyDown = useCallback(
     (e: KeyboardEvent<HTMLButtonElement>) => {
       if (e.key === "ArrowRight" || e.key === "ArrowDown") {
         e.preventDefault();
-        onChange("file");
+        selectValue("file");
       } else if (e.key === "ArrowLeft" || e.key === "ArrowUp") {
         e.preventDefault();
-        onChange("diff");
+        selectValue("diff");
       }
     },
-    [onChange],
+    [selectValue],
   );
 
   return (
@@ -280,11 +293,14 @@ function ViewerModeToggle({
         aria-label="File view"
         className="inline-flex rounded-md bg-muted p-0.5"
       >
-        {options.map((option) => {
+        {options.map((option, index) => {
           const isSelected = value === option.value;
           return (
             <button
               key={option.value}
+              ref={(el) => {
+                buttonRefs.current[index] = el;
+              }}
               type="button"
               role="radio"
               aria-checked={isSelected}
@@ -340,7 +356,12 @@ function FileViewerBody({
 
   if (isLoading) {
     return (
-      <div className="space-y-2 p-4" aria-busy="true" aria-label="Loading file">
+      <div
+        role="status"
+        className="space-y-2 p-4"
+        aria-busy="true"
+        aria-label="Loading file"
+      >
         {SKELETON_LINE_WIDTHS.map((width, i) => (
           <div
             key={i}

package/src/workspace/WorkspaceContentSearch.tsx

@@ -161,8 +161,28 @@ export function WorkspaceContentSearch({
   const belowMinLength = trimmed.length > 0 && trimmed.length < MIN_QUERY_LENGTH;
   const showEntryHeaders = groups.length > 1;
 
+  // Screen-reader-only summary in a persistent polite live region: status swaps
+  // (searching → results/none) happen across separate unmounting branches, so a
+  // stable region is what actually gets announced. Terse by design.
+  const statusMessage = isUnsupported
+    ? ""
+    : trimmed.length === 0
+      ? ""
+      : belowMinLength
+        ? `Type at least ${MIN_QUERY_LENGTH} characters to search.`
+        : isLoading
+          ? "Searching file contents…"
+          : groups.length === 0
+            ? `No files containing ${trimmed}.`
+            : totalMatches > flatResults.length
+              ? `Showing the first ${flatResults.length} of ${totalMatches} matches.`
+              : `${totalMatches} ${totalMatches === 1 ? "match" : "matches"}.`;
+
   return (
     <div className={cn("flex h-full flex-col", className)}>
+      <div role="status" aria-live="polite" className="sr-only">
+        {statusMessage}
+      </div>
       <div className="flex items-center gap-1.5 border-b border-border px-2 py-1.5">
         <SearchIcon />
         <input
@@ -336,27 +356,31 @@ function LineRow({
   readonly isOpen: boolean;
   readonly onOpen: () => void;
 }) {
+  // The `role="option"` IS the interactive leaf of the listbox (keyboard
+  // activation flows through the combobox input's Enter handler +
+  // aria-activedescendant). It must not nest another interactive control — a
+  // button inside would violate WCAG 4.1.2 (axe `nested-interactive`). So the
+  // click handler and row styling live on the option itself.
   return (
-    <li id={id} role="option" aria-selected={isFocused}>
-      <button
-        type="button"
-        onClick={onOpen}
-        tabIndex={-1}
-        aria-current={isOpen ? "true" : undefined}
-        className={cn(
-          "flex w-full items-baseline gap-2 py-0.5 pl-6 pr-3 text-left text-xs transition-colors",
-          isFocused && "bg-muted",
-          isOpen && "bg-muted",
-          !isFocused && !isOpen && "hover:bg-muted",
-        )}
-      >
-        <span className="w-8 shrink-0 text-right font-mono text-[0.65rem] tabular-nums text-muted-foreground-subtle">
-          {match.line}
-        </span>
-        <span className="min-w-0 flex-1 truncate font-mono text-muted-foreground">
-          <HighlightedPreview text={match.preview} query={query} />
-        </span>
-      </button>
+    <li
+      id={id}
+      role="option"
+      aria-selected={isFocused}
+      aria-current={isOpen ? "true" : undefined}
+      onClick={onOpen}
+      className={cn(
+        "flex cursor-pointer items-baseline gap-2 py-0.5 pl-6 pr-3 text-xs transition-colors",
+        isFocused && "bg-muted",
+        isOpen && "bg-muted",
+        !isFocused && !isOpen && "hover:bg-muted",
+      )}
+    >
+      <span className="w-8 shrink-0 text-right font-mono text-[0.65rem] tabular-nums text-muted-foreground-subtle">
+        {match.line}
+      </span>
+      <span className="min-w-0 flex-1 truncate font-mono text-muted-foreground">
+        <HighlightedPreview text={match.preview} query={query} />
+      </span>
     </li>
   );
 }