refactor(agent): ReasoningBlock replaces ActivityBlock on native details (CL-8482)

Author: TheGreatAxios

ARCHITECTURE.md

@@ -219,6 +219,7 @@ in `useState` with no way for a parent to read or drive it.
 | `NotificationsBell` | `src/ui/notifications-bell.tsx` | 1 importer | **Fixed** — added optional `open`/`onOpenChange` |
 | `TenantSelector` | `src/ui/tenant-selector.tsx` | 1 importer | **Fixed** — added optional `open`/`onOpenChange` |
 | `ThreadSwitcher` | `src/ui/thread-switcher.tsx` | 1 importer | **Fixed** — added optional `open`/`onOpenChange` |
+| `ReasoningBlock` (was `ActivityBlock`) | `src/ui/reasoning-block.tsx` | 1 importer | **Fixed** — added optional `open`/`onOpenChange` over the native `<details>` |
 | `SubagentDock` (per-row disclosure) | `src/ui/subagent-dock.tsx` | 1 importer | Deferred — lifting it means a parent tracking one open flag per subagent row (a map, not a boolean); a bigger surface change than this pass covers |
 
 All five fixes are additive: `open`/`onOpenChange` are optional, and the
@@ -227,10 +228,7 @@ calls these components today changes behavior.
 
 A few more components hold local `open`/`expanded`-shaped state and were
 checked against the same bar, but don't belong on the fix list:
-`ActivityBlock` is backed by a native `<details>` on purpose (see its own
-doc comment) — the browser supplies the disclosure semantics, keyboard
-behavior and find-in-page expansion, which making it controlled would mean
-re-deriving by hand. `ApprovalCard`'s per-detail "show more" is a text
+`ApprovalCard`'s per-detail "show more" is a text
 truncation toggle, not a layout region — nobody outside the row has a reason
 to know or set it. `ConfirmButton`'s `armed` state is already documented as
 deliberately uncontrolled (`defaultArmed` only seeds the initial value).
@@ -347,8 +345,8 @@ pair: `open` + `onOpenChange`, or `collapsed` + `onToggle`. `Sidebar` sets
 this precedent; `Dialog` and `CommandPalette` apply it to popups;
 `NotificationsBell`, `ToolBlock` and `ToolNarrative` do too, all
 uncontrolled-by-default so adding the pair is never a breaking change. The
-exception is state a parent has no legitimate reason to want: `ActivityBlock`
-stays a native `<details>`, and a text-truncation toggle stays local. If
+exception is state a parent has no legitimate reason to want: a
+text-truncation toggle stays local. If
 you're unsure which side of that line something is on, ask "would a real
 caller ever need to read or set this from outside" — not "could they."
 

CHANGELOG.md

@@ -37,6 +37,10 @@ contract — modules that are not exported are internal and may change in any re
   `activity-block` stayed — `chat-thread` uses them. The package is now 113
   public modules. **`@tanstack/react-query` is no longer a peer dependency** —
   nothing in the package imports it.
+- **`ActivityBlock` is renamed `ReasoningBlock`** (module `reasoning-block`),
+  aligned with `reasoningText()` naming. The prop `working` is now `streaming`,
+  and it gains `durationLabel` plus the optional `open`/`onOpenChange`
+  controlled pair while staying a native `<details>`.
 - **`AuthLayout` no longer defaults its decorative panel to `DitherCanvas`.** The panel is
   now an explicit `panel` slot with no fallback — pass `<DitherCanvas />` or any other
   content. A caller that omitted `panel` to get the dither canvas for free now gets a

package.json

@@ -191,10 +191,6 @@
       "types": "./dist/lib/workflow-run-progress.d.ts",
       "default": "./dist/lib/workflow-run-progress.js"
     },
-    "./ui/activity-block": {
-      "types": "./dist/ui/activity-block.d.ts",
-      "default": "./dist/ui/activity-block.js"
-    },
     "./ui/agent-turn": {
       "types": "./dist/ui/agent-turn.d.ts",
       "default": "./dist/ui/agent-turn.js"
@@ -415,6 +411,10 @@
       "types": "./dist/ui/quote-card.d.ts",
       "default": "./dist/ui/quote-card.js"
     },
+    "./ui/reasoning-block": {
+      "types": "./dist/ui/reasoning-block.d.ts",
+      "default": "./dist/ui/reasoning-block.js"
+    },
     "./ui/research-body": {
       "types": "./dist/ui/research-body.d.ts",
       "default": "./dist/ui/research-body.js"

src/index.ts

@@ -33,7 +33,6 @@ export * from "./lib/workflow-registry.js";
 export * from "./lib/workflow-run.js";
 export * from "./lib/workflow-run-error.js";
 export * from "./lib/workflow-run-progress.js";
-export * from "./ui/activity-block.js";
 export * from "./ui/agent-turn.js";
 export * from "./ui/animated-number.js";
 export * from "./ui/approval-card.js";
@@ -89,6 +88,7 @@ export * from "./ui/progress-checklist.js";
 export * from "./ui/provider-mark.js";
 export * from "./ui/quick-reply-chips.js";
 export * from "./ui/quote-card.js";
+export * from "./ui/reasoning-block.js";
 export * from "./ui/research-body.js";
 export * from "./ui/rich-empty-state.js";
 export * from "./ui/run-now-button.js";

src/ui/activity-block.tsx

@@ -13,64 +13,72 @@ function mount(props: ComponentProps<typeof ReasoningBlock>) {
     root.render(createElement(ReasoningBlock, props));
   });
   return {
-    button: () => container.querySelector("button") as HTMLButtonElement,
-    region: () => container.querySelector('[role="region"]'),
+    details: () => container.querySelector("details"),
+    summary: () => container.querySelector("summary"),
+    body: () => container.querySelector("details > p"),
     unmount: () => act(() => root.unmount()),
   };
 }
 
 describe("ReasoningBlock", () => {
   test("renders nothing for empty reasoning text", () => {
-    const { button, unmount } = mount({ text: "   " });
-    expect(button()).toBeNull();
+    const { details, unmount } = mount({ text: "   " });
+    expect(details()).toBeNull();
     unmount();
   });
 
-  test("is collapsed by default and toggles open on click", () => {
-    const { button, region, unmount } = mount({ text: "Weighing two options." });
-    expect(button().getAttribute("aria-expanded")).toBe("false");
-    expect(region()).toBeNull();
+  test("is collapsed by default and opens via the details toggle", () => {
+    const { details, summary, body, unmount } = mount({ text: "Weighing two options." });
+    expect(details()?.hasAttribute("open")).toBe(false);
+    expect(body()).toBeTruthy();
 
+    const el = details() as HTMLDetailsElement;
     act(() => {
-      button().dispatchEvent(new MouseEvent("click", { bubbles: true }));
+      el.open = true;
+      el.dispatchEvent(new Event("toggle"));
     });
 
-    expect(button().getAttribute("aria-expanded")).toBe("true");
-    expect(region()?.textContent).toBe("Weighing two options.");
+    expect(details()?.hasAttribute("open")).toBe(true);
+    expect(body()?.textContent).toBe("Weighing two options.");
+    expect(summary()).toBeTruthy();
     unmount();
   });
 
   test("shows the duration label once idle, and \"Thinking…\" while streaming", () => {
     const idle = mount({ text: "Done thinking.", durationLabel: "Thought for 4s" });
-    expect(idle.button().textContent).toBe("Thought for 4s");
+    expect(idle.summary()?.textContent).toBe("Thought for 4s");
     idle.unmount();
 
     const streaming = mount({ text: "Still going.", streaming: true, durationLabel: "Thought for 4s" });
-    expect(streaming.button().textContent).toBe("Thinking…");
+    expect(streaming.summary()?.textContent).toBe("Thinking…");
     streaming.unmount();
   });
 
   test("idle without a duration label uses Thinking, not a cute fallback", () => {
     const idle = mount({ text: "Done thinking." });
-    expect(idle.button().textContent).toBe("Thinking");
-    expect(idle.button().textContent).not.toContain("Thought about this");
+    expect(idle.summary()?.textContent).toBe("Thinking");
+    expect(idle.summary()?.textContent).not.toContain("Thought about this");
     idle.unmount();
   });
 
-  test("two mounted blocks have distinct region ids matching their toggles", () => {
-    const first = mount({ text: "First thought.", defaultOpen: true });
-    const second = mount({ text: "Second thought.", defaultOpen: true });
-
-    const firstControls = first.button().getAttribute("aria-controls");
-    const secondControls = second.button().getAttribute("aria-controls");
+  test("controlled open state reports toggles through onOpenChange", () => {
+    let seen: boolean | undefined;
+    const { details, unmount } = mount({
+      text: "Controlled.",
+      open: true,
+      onOpenChange: (next) => {
+        seen = next;
+      },
+    });
+    expect(details()?.hasAttribute("open")).toBe(true);
 
-    expect(firstControls).toBeTruthy();
-    expect(secondControls).toBeTruthy();
-    expect(firstControls).not.toBe(secondControls);
-    expect(first.region()?.id ?? null).toBe(firstControls);
-    expect(second.region()?.id ?? null).toBe(secondControls);
+    const el = details() as HTMLDetailsElement;
+    act(() => {
+      el.open = false;
+      el.dispatchEvent(new Event("toggle"));
+    });
 
-    first.unmount();
-    second.unmount();
+    expect(seen).toBe(false);
+    unmount();
   });
 });

src/ui/reasoning-block.test.tsx

@@ -1,15 +1,14 @@
 import { ChevronRight } from "lucide-react";
-import { useId } from "react";
 
 import { useControllableState } from "../hooks/use-controllable-state.js";
 import { cn } from "../lib/utils.js";
 
 export type ReasoningBlockProps = {
   /** The agent's thinking. Rendered as text — it is not markup. */
   readonly text: string;
-  /** Still streaming. Changes the summary wording and marks the region busy. */
+  /** Still streaming. Changes the summary wording and marks the body busy. */
   readonly streaming?: boolean;
-  /** e.g. "Thought for 4s". Shown once reasoning has stopped streaming. */
+  /** e.g. "Thought for 4s". Becomes the summary once reasoning has stopped streaming. */
   readonly durationLabel?: string;
   readonly defaultOpen?: boolean;
   /** Controlled open state. Pair with `onOpenChange` to lift it to a parent. */
@@ -25,9 +24,9 @@ export type ReasoningBlockProps = {
  * reader who wants it and noise for one who does not, and a block that
  * expands itself mid-stream makes the transcript jump under the reader.
  *
- * A `button` + region pair rather than a native `<details>` — the duration
- * label needs to sit next to the summary text without becoming part of it,
- * which `<summary>` cannot do while keeping a single accessible name.
+ * A native `<details>`, not a div with state: it gets the disclosure
+ * semantics, keyboard behaviour and find-in-page expansion from the browser,
+ * and those are three things a hand-rolled version gets wrong.
  */
 export function ReasoningBlock({
   text,
@@ -44,35 +43,33 @@ export function ReasoningBlock({
     onChange: onOpenChange,
     name: "ReasoningBlock",
   });
-  const regionId = useId();
 
   if (text.trim().length === 0) return null;
 
   const summary = streaming ? "Thinking…" : (durationLabel ?? "Thinking");
 
   return (
-    <div data-slot="reasoning-block" className={cn("text-xs", className)}>
-      <button
-        type="button"
-        onClick={() => setOpen((value) => !value)}
-        aria-expanded={open}
-        aria-controls={regionId}
-        className="flex w-full items-center gap-1.5 rounded-md px-2 py-1.5 text-left text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+    <details
+      data-slot="reasoning-block"
+      open={open}
+      onToggle={(event) => setOpen((event.currentTarget as HTMLDetailsElement).open)}
+      className={cn("text-xs", className)}
+    >
+      <summary
+        className={cn(
+          "flex cursor-pointer list-none items-center gap-1.5 rounded-md px-2 py-1.5 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground",
+          "[&::-webkit-details-marker]:hidden",
+        )}
       >
         <ChevronRight className={cn("size-3.5 shrink-0 transition-transform", open && "rotate-90")} aria-hidden />
         <span aria-live={streaming ? "polite" : undefined}>{summary}</span>
-      </button>
-      {open ? (
-        <p
-          id={regionId}
-          role="region"
-          aria-label="Reasoning"
-          aria-busy={streaming}
-          className="mt-1 ml-4 border-l border-border pl-3 leading-relaxed whitespace-pre-wrap text-muted-foreground"
-        >
-          {text}
-        </p>
-      ) : null}
-    </div>
+      </summary>
+      <p
+        aria-busy={streaming}
+        className="mt-1 ml-4 border-l border-border pl-3 leading-relaxed whitespace-pre-wrap text-muted-foreground"
+      >
+        {text}
+      </p>
+    </details>
   );
 }