@elabs-ai/components-ai 4.0.0 → 4.2.0

package/src/session-status-bar.tsx

@@ -0,0 +1,165 @@
+"use client";
+
+import { cn, useLocale } from "@elabs-ai/components-ui";
+import { Cpu, Folder, GitBranch, Loader2Icon, PlugZapIcon } from "lucide-react";
+import type { ComponentProps, ComponentType, ReactNode, SVGProps } from "react";
+import { forwardRef } from "react";
+
+export interface SessionStatusBarConnections {
+  /** Number of integrations/MCP servers currently connected. */
+  connected: number;
+  /** Total number of configured integrations/MCP servers. */
+  total: number;
+  /** Renders a spinner in place of the connection icon while establishing. */
+  connecting?: boolean;
+}
+
+export interface SessionStatusBarProps extends ComponentProps<"div"> {
+  /** Current workspace/project name. */
+  workspace?: string;
+  /** Current git branch. */
+  branch?: string;
+  /** Active model id/label. */
+  model?: string;
+  /** Integration/MCP connection progress; renders a spinner while connecting. */
+  connections?: SessionStatusBarConnections;
+  /**
+   * Docks another component alongside the ambient segments — most often
+   * `<TokenUsage />` (`@elabs-ai/components-ai`), so token usage/cost keeps
+   * its one owner (`token-usage.tsx`, tokenlens) instead of being re-implemented
+   * here. Rendered flush to the end of the bar.
+   */
+  children?: ReactNode;
+}
+
+type SegmentIcon = ComponentType<SVGProps<SVGSVGElement>>;
+
+const SessionStatusBarSegment = ({
+  icon: Icon,
+  slot,
+  value,
+}: {
+  icon: SegmentIcon;
+  slot: string;
+  value: string;
+}) => (
+  <span className="inline-flex min-w-0 items-center gap-1.5" data-slot={slot}>
+    <Icon aria-hidden="true" className="size-3.5 shrink-0" />
+    <span className="truncate">{value}</span>
+  </span>
+);
+
+/**
+ * SessionStatusBar — the ambient session row: workspace, branch, model, and
+ * integration-connection progress (#105). Every segment is independently
+ * optional and renders only when its prop is supplied; with nothing supplied
+ * the bar renders nothing at all, not an empty shell.
+ *
+ * Docks `Context` (or any other node) via `children` rather than
+ * re-implementing token-usage/cost maths — `context.tsx` stays the one owner
+ * of that calculation (tokenlens).
+ */
+export const SessionStatusBar = forwardRef<HTMLDivElement, SessionStatusBarProps>(
+  function SessionStatusBar(
+    { workspace, branch, model, connections, children, className, ...props },
+    ref,
+  ) {
+    const { formatNumber, t } = useLocale();
+    const hasContent = Boolean(workspace ?? branch ?? model ?? connections ?? children);
+
+    if (!hasContent) {
+      return null;
+    }
+
+    // Computed once and reused for BOTH the connections region's name (for a
+    // user who navigates to it deliberately) and its real, non-hidden text
+    // content — what a polite announcement actually reads on change. An
+    // aria-label alone is NOT that (#155): a live region announces its
+    // content, not its own accessible name.
+    const connectionsAnnouncement = connections
+      ? connections.connecting
+        ? t("ai.sessionStatusBar.connecting")
+        : t("ai.sessionStatusBar.connections", {
+            connected: connections.connected,
+            total: connections.total,
+          })
+      : undefined;
+
+    return (
+      <div
+        ref={ref}
+        className={cn(
+          "flex w-full items-center gap-4 border-t bg-surface-muted px-3 py-1.5 text-meta text-muted-foreground",
+          className,
+        )}
+        data-slot="session-status-bar"
+        {...props}
+      >
+        {workspace ? (
+          <SessionStatusBarSegment
+            icon={Folder}
+            slot="session-status-bar-workspace"
+            value={workspace}
+          />
+        ) : null}
+        {branch ? (
+          <SessionStatusBarSegment
+            icon={GitBranch}
+            slot="session-status-bar-branch"
+            value={branch}
+          />
+        ) : null}
+        {model ? (
+          <SessionStatusBarSegment icon={Cpu} slot="session-status-bar-model" value={model} />
+        ) : null}
+        {connections ? (
+          <span
+            aria-live="polite"
+            className="inline-flex shrink-0 items-center gap-1.5"
+            data-slot="session-status-bar-connections"
+            role="status"
+          >
+            {connections.connecting ? (
+              <Loader2Icon
+                aria-hidden="true"
+                className="size-3.5 shrink-0 animate-spin motion-reduce:animate-none"
+              />
+            ) : (
+              <PlugZapIcon aria-hidden="true" className="size-3.5 shrink-0" />
+            )}
+            <span aria-hidden="true" className="tabular-nums">
+              {formatNumber(connections.connected)}/{formatNumber(connections.total)}
+            </span>
+            {/* The live region's only NON-hidden text — mirrors
+                terminal-status-bar.tsx's aria-hidden-visual +
+                sr-only-sentence pair (#155). Without this, every polite
+                update announced an empty string: the counter above is
+                aria-hidden, so it was the region's ONLY text content.
+                Deliberately no `aria-label` here (unlike
+                terminal-status-bar.tsx, where the label lives on the OUTER
+                bar as a generic region name distinct from any segment's
+                content): an explicit `aria-label` here would give this
+                span an ACCESSIBLE NAME byte-identical to its announced
+                CONTENT, which risks a double announcement ("Connecting…
+                Connecting…") on ATs that speak a live region's name
+                alongside its changed content. Leaving `aria-label` off
+                does NOT relocate the name to this text — `role="status"`
+                is `nameFrom: author`, so it never falls back to content
+                the way e.g. a `button` does. The span simply has no
+                accessible name, which is fine: no acceptance criterion
+                needs one here, only the announced content does. */}
+            <span className="sr-only">{connectionsAnnouncement}</span>
+          </span>
+        ) : null}
+        {children ? (
+          <div
+            className="ms-auto flex shrink-0 items-center"
+            data-slot="session-status-bar-context"
+          >
+            {children}
+          </div>
+        ) : null}
+      </div>
+    );
+  },
+);

package/src/snippet.stories.tsx

@@ -3,7 +3,15 @@ import { Snippet, SnippetAddon, SnippetCopyButton, SnippetInput } from "./snippe
 const meta = {
   title: "AI/Snippet",
   component: Snippet,
-  parameters: { layout: "padded" },
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        component:
+          "A single-line copyable COMMAND — an `InputGroup` in a mono face wrapping a read-only value and a copy button (`npm i …`, a curl line, an id). Multi-line highlighted source with a language picker is `AI/CodeBlock`; see [Choosing between similar components](?path=/docs/docs-choosing-between-similar-components--docs). Nothing here highlights: `Snippet` never loads Shiki.",
+      },
+    },
+  },
 } satisfies Meta<typeof Snippet>;
 export default meta;
 type Story = StoryObj<typeof meta>;

package/src/snippet.test.tsx

@@ -88,7 +88,7 @@ describe("SnippetCopyButton", () => {
     await waitFor(() => expect(onError).toHaveBeenCalled());
   });
 
-  it("reports an UNAVAILABLE clipboard through onError (insecure context / old browser)", () => {
+  it("reports an UNAVAILABLE clipboard through onError (insecure context / old browser)", async () => {
     Object.defineProperty(navigator, "clipboard", { value: undefined, configurable: true });
     const onError = vi.fn();
     render(
@@ -98,7 +98,11 @@ describe("SnippetCopyButton", () => {
       </Snippet>,
     );
     fireEvent.click(screen.getByRole("button", { name: "Copy" }));
-    expect(onError).toHaveBeenCalled();
+    // The shared `useCopyToClipboard` hook (`@elabs-ai/components-ui`) always
+    // resolves `copy()` on a microtask, even for the synchronous
+    // "clipboard missing" case — so this needs a `waitFor`, unlike a
+    // hand-rolled synchronous check would have.
+    await waitFor(() => expect(onError).toHaveBeenCalled());
   });
 
   it("fires onCopy once the write resolves", async () => {

package/src/snippet.tsx

@@ -8,18 +8,10 @@ import {
   InputGroupText,
 } from "@elabs-ai/components-ui";
 import { cn } from "@elabs-ai/components-ui/lib/cn";
-import { useLocale } from "@elabs-ai/components-ui";
+import { useCopyToClipboard, useLocale } from "@elabs-ai/components-ui";
 import { CheckIcon, CopyIcon } from "lucide-react";
 import type { ComponentProps } from "react";
-import {
-  createContext,
-  useCallback,
-  useContext,
-  useEffect,
-  useMemo,
-  useRef,
-  useState,
-} from "react";
+import { createContext, useCallback, useContext, useMemo } from "react";
 
 interface SnippetContextType {
   code: string;
@@ -79,40 +71,28 @@ export type SnippetCopyButtonProps = ComponentProps<typeof InputGroupButton> & {
 export const SnippetCopyButton = ({
   onCopy,
   onError,
-  timeout = 2000,
+  timeout,
   children,
   className,
   ...props
 }: SnippetCopyButtonProps) => {
   const { t } = useLocale();
-  const [isCopied, setIsCopied] = useState(false);
-  const timeoutRef = useRef<number>(0);
   const { code } = useContext(SnippetContext);
+  // Shared implementation (`@elabs-ai/components-ui`) instead of a private
+  // copy of the same copy-to-clipboard state machine (issue-workflow.md
+  // dedupe finding) — see `CodeBlockCopyButton` for the reference usage.
+  const { copied: isCopied, copy } = useCopyToClipboard(
+    timeout === undefined ? undefined : { resetAfterMs: timeout },
+  );
 
   const copyToClipboard = useCallback(async () => {
-    if (typeof window === "undefined" || !navigator?.clipboard?.writeText) {
+    const ok = await copy(code);
+    if (ok) {
+      onCopy?.();
+    } else {
       onError?.(new Error("Clipboard API not available"));
-      return;
-    }
-
-    try {
-      if (!isCopied) {
-        await navigator.clipboard.writeText(code);
-        setIsCopied(true);
-        onCopy?.();
-        timeoutRef.current = window.setTimeout(() => setIsCopied(false), timeout);
-      }
-    } catch (error) {
-      onError?.(error as Error);
     }
-  }, [code, onCopy, onError, timeout, isCopied]);
-
-  useEffect(
-    () => () => {
-      window.clearTimeout(timeoutRef.current);
-    },
-    [],
-  );
+  }, [copy, code, onCopy, onError]);
 
   const Icon = isCopied ? CheckIcon : CopyIcon;
 

package/src/speech-input.test.tsx

@@ -0,0 +1,109 @@
+/**
+ * speech-input.test.tsx — the MediaRecorder fallback path's two race bugs:
+ * a double click starting two recorders before the first `getUserMedia()`
+ * resolves, and an unmount during a pending `getUserMedia()` leaving the
+ * microphone on with nothing left to stop it.
+ */
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { cleanup, fireEvent, render, waitFor } from "@testing-library/react";
+import { SpeechInput } from "./speech-input";
+
+class FakeMediaRecorder {
+  state: "inactive" | "recording" = "inactive";
+  private listeners = new Map<string, Set<(event: Event) => void>>();
+
+  constructor(public stream: MediaStream) {}
+
+  addEventListener(type: string, cb: (event: Event) => void) {
+    if (!this.listeners.has(type)) this.listeners.set(type, new Set());
+    this.listeners.get(type)?.add(cb);
+  }
+
+  removeEventListener(type: string, cb: (event: Event) => void) {
+    this.listeners.get(type)?.delete(cb);
+  }
+
+  start() {
+    this.state = "recording";
+  }
+
+  stop() {
+    this.state = "inactive";
+    for (const cb of this.listeners.get("stop") ?? []) cb(new Event("stop"));
+  }
+}
+
+function makeFakeStream() {
+  const tracks = [{ stop: vi.fn() }, { stop: vi.fn() }];
+  return {
+    getTracks: () => tracks,
+    tracks,
+  } as unknown as MediaStream & { tracks: { stop: ReturnType<typeof vi.fn> }[] };
+}
+
+function stubMediaRecorderEnvironment(getUserMedia: (...args: unknown[]) => unknown) {
+  vi.stubGlobal("MediaRecorder", FakeMediaRecorder);
+  Object.defineProperty(navigator, "mediaDevices", {
+    configurable: true,
+    value: { getUserMedia },
+  });
+}
+
+afterEach(() => {
+  cleanup();
+  vi.unstubAllGlobals();
+  // @ts-expect-error -- test-only cleanup of a property we defined above
+  delete navigator.mediaDevices;
+});
+
+describe("SpeechInput — media-recorder fallback getUserMedia race guards", () => {
+  it("does not call getUserMedia twice for a double click before the first call resolves", async () => {
+    let resolveGetUserMedia: ((stream: MediaStream) => void) | undefined;
+    const getUserMedia = vi.fn(
+      () =>
+        new Promise((resolve: (stream: MediaStream) => void) => {
+          resolveGetUserMedia = resolve;
+        }),
+    );
+    stubMediaRecorderEnvironment(getUserMedia);
+
+    const startSpy = vi.spyOn(FakeMediaRecorder.prototype, "start");
+    const { getByRole } = render(<SpeechInput onAudioRecorded={() => Promise.resolve("hi")} />);
+    const button = getByRole("button");
+
+    fireEvent.click(button);
+    fireEvent.click(button);
+
+    expect(getUserMedia).toHaveBeenCalledTimes(1);
+
+    resolveGetUserMedia?.(makeFakeStream());
+    // Only ONE recorder is ever created/started — the second click's
+    // `getUserMedia()` call was suppressed by the in-flight guard, not merely
+    // delayed.
+    await waitFor(() => expect(startSpy).toHaveBeenCalledTimes(1));
+  });
+
+  it("stops the granted tracks when the component unmounts before getUserMedia resolves", async () => {
+    let resolveGetUserMedia: ((stream: MediaStream) => void) | undefined;
+    const getUserMedia = vi.fn(
+      () =>
+        new Promise((resolve: (stream: MediaStream) => void) => {
+          resolveGetUserMedia = resolve;
+        }),
+    );
+    stubMediaRecorderEnvironment(getUserMedia);
+
+    const { getByRole, unmount } = render(
+      <SpeechInput onAudioRecorded={() => Promise.resolve("hi")} />,
+    );
+    fireEvent.click(getByRole("button"));
+
+    unmount();
+
+    const stream = makeFakeStream();
+    resolveGetUserMedia?.(stream);
+
+    await waitFor(() => expect(stream.tracks[0]?.stop).toHaveBeenCalledTimes(1));
+    expect(stream.tracks[1]?.stop).toHaveBeenCalledTimes(1);
+  });
+});

package/src/speech-input.tsx

@@ -101,6 +101,21 @@ export const SpeechInput = ({
   const onTranscriptionChangeRef =
     useRef<SpeechInputProps["onTranscriptionChange"]>(onTranscriptionChange);
   const onAudioRecordedRef = useRef<SpeechInputProps["onAudioRecorded"]>(onAudioRecorded);
+  // Guards a pending `getUserMedia()` call against a second click/toggle
+  // firing before the first resolves (both see `isListening === false`, since
+  // that flips only once the stream is actually granted).
+  const isStartingMediaRecorderRef = useRef(false);
+  // Flips false on unmount so an in-flight `getUserMedia()` that resolves
+  // AFTER teardown stops its just-granted tracks immediately instead of
+  // leaving the microphone on with nothing listening.
+  const isMountedRef = useRef(true);
+
+  useEffect(
+    () => () => {
+      isMountedRef.current = false;
+    },
+    [],
+  );
 
   // Keep refs in sync
   onTranscriptionChangeRef.current = onTranscriptionChange;
@@ -183,12 +198,23 @@ export const SpeechInput = ({
 
   // Start MediaRecorder recording
   const startMediaRecorder = useCallback(async () => {
-    if (!onAudioRecordedRef.current) {
+    if (!onAudioRecordedRef.current || isStartingMediaRecorderRef.current) {
       return;
     }
 
+    isStartingMediaRecorderRef.current = true;
     try {
       const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+
+      // Unmounted (or stopped) while getUserMedia was pending — the granted
+      // tracks have no listener left to stop them later, so stop them now.
+      if (!isMountedRef.current) {
+        for (const track of stream.getTracks()) {
+          track.stop();
+        }
+        return;
+      }
+
       streamRef.current = stream;
       const mediaRecorder = new MediaRecorder(stream);
       audioChunksRef.current = [];
@@ -241,6 +267,8 @@ export const SpeechInput = ({
       setIsListening(true);
     } catch {
       setIsListening(false);
+    } finally {
+      isStartingMediaRecorderRef.current = false;
     }
   }, []);
 
@@ -281,7 +309,7 @@ export const SpeechInput = ({
       {isListening &&
         [0, 1, 2].map((index) => (
           <div
-            className="absolute inset-0 animate-ping rounded-full border-2 border-red-400/30"
+            className="absolute inset-0 animate-ping rounded-full border-2 border-destructive/30"
             key={index}
             style={{
               animationDelay: `${index * 0.3}s`,
@@ -295,7 +323,7 @@ export const SpeechInput = ({
         className={cn(
           "relative z-10 rounded-full transition-colors duration-slow ease-standard motion-reduce:transition-none",
           isListening
-            ? "bg-destructive text-white hover:bg-destructive/80 hover:text-white"
+            ? "bg-destructive text-destructive-foreground hover:bg-destructive/80 hover:text-destructive-foreground"
             : "bg-primary text-primary-foreground hover:bg-primary/80 hover:text-primary-foreground",
           className,
         )}

package/src/stack-trace.tsx

@@ -3,19 +3,11 @@
 import { useControllableState } from "@radix-ui/react-use-controllable-state";
 import { Button } from "@elabs-ai/components-ui";
 import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "@elabs-ai/components-ui";
+import { useCopyToClipboard, useLocale } from "@elabs-ai/components-ui";
 import { cn } from "@elabs-ai/components-ui/lib/cn";
 import { AlertTriangleIcon, CheckIcon, ChevronDownIcon, CopyIcon } from "lucide-react";
 import type { ComponentProps } from "react";
-import {
-  createContext,
-  memo,
-  useCallback,
-  useContext,
-  useEffect,
-  useMemo,
-  useRef,
-  useState,
-} from "react";
+import { createContext, memo, useCallback, useContext, useMemo } from "react";
 
 // Regex patterns for parsing stack traces
 const STACK_FRAME_WITH_PARENS_REGEX = /^at\s+(.+?)\s+\((.+):(\d+):(\d+)\)$/;
@@ -187,7 +179,7 @@ export const StackTrace = memo(
       <StackTraceContext.Provider value={contextValue}>
         <div
           className={cn(
-            "not-prose w-full overflow-hidden rounded-lg border bg-background font-mono text-sm",
+            "not-prose w-full overflow-hidden rounded-lg border bg-background font-mono text-body",
             className,
           )}
           {...props}
@@ -236,7 +228,9 @@ export const StackTraceErrorType = memo(
     const { trace } = useStackTrace();
 
     return (
-      <span className={cn("shrink-0 font-semibold text-destructive", className)} {...props}>
+      // #124: the error type NAME is running text (e.g. "TypeError"), not a
+      // mark — ink rung, unlike the AlertTriangleIcon mark above.
+      <span className={cn("shrink-0 font-semibold text-destructive-text", className)} {...props}>
         {children ?? trace.errorType}
       </span>
     );
@@ -290,42 +284,35 @@ export const StackTraceCopyButton = memo(
   ({
     onCopy,
     onError,
-    timeout = 2000,
+    timeout,
     className,
     children,
+    "aria-label": ariaLabel,
     ...props
   }: StackTraceCopyButtonProps) => {
-    const [isCopied, setIsCopied] = useState(false);
-    const timeoutRef = useRef<number>(0);
+    const { t } = useLocale();
     const { raw } = useStackTrace();
+    // Shared implementation (`@elabs-ai/components-ui`) instead of a private
+    // copy of the same copy-to-clipboard state machine (issue-workflow.md
+    // dedupe finding) — see `CodeBlockCopyButton` for the reference usage.
+    const { copied: isCopied, copy } = useCopyToClipboard(
+      timeout === undefined ? undefined : { resetAfterMs: timeout },
+    );
 
     const copyToClipboard = useCallback(async () => {
-      if (typeof window === "undefined" || !navigator?.clipboard?.writeText) {
-        onError?.(new Error("Clipboard API not available"));
-        return;
-      }
-
-      try {
-        await navigator.clipboard.writeText(raw);
-        setIsCopied(true);
+      const ok = await copy(raw);
+      if (ok) {
         onCopy?.();
-        timeoutRef.current = window.setTimeout(() => setIsCopied(false), timeout);
-      } catch (error) {
-        onError?.(error as Error);
+      } else {
+        onError?.(new Error("Clipboard API not available"));
       }
-    }, [raw, onCopy, onError, timeout]);
-
-    useEffect(
-      () => () => {
-        window.clearTimeout(timeoutRef.current);
-      },
-      [],
-    );
+    }, [copy, raw, onCopy, onError]);
 
     const Icon = isCopied ? CheckIcon : CopyIcon;
 
     return (
       <Button
+        aria-label={ariaLabel ?? t("copy")}
         className={cn("size-7", className)}
         onClick={copyToClipboard}
         size="icon"
@@ -426,6 +413,7 @@ FilePathButton.displayName = "FilePathButton";
 export const StackTraceFrames = memo(
   ({ className, showInternalFrames = true, ...props }: StackTraceFramesProps) => {
     const { trace, onFilePathClick } = useStackTrace();
+    const { t } = useLocale();
 
     const framesToShow = showInternalFrames
       ? trace.frames
@@ -436,7 +424,7 @@ export const StackTraceFrames = memo(
         {framesToShow.map((frame) => (
           <div
             className={cn(
-              "text-xs",
+              "text-meta",
               frame.isInternal ? "text-muted-foreground/50" : "text-foreground/90",
             )}
             key={frame.raw}
@@ -460,7 +448,7 @@ export const StackTraceFrames = memo(
           </div>
         ))}
         {framesToShow.length === 0 && (
-          <div className="text-muted-foreground text-xs">No stack frames</div>
+          <div className="text-muted-foreground text-meta">{t("ai.stackTrace.empty")}</div>
         )}
       </div>
     );

package/src/streamdown-i18n.test.tsx

@@ -13,6 +13,7 @@ import { LocaleProvider } from "@elabs-ai/components-ui";
 import { MessageResponse } from "./message";
 import { MarkdownView } from "./markdown-view";
 import { Reasoning, ReasoningContent } from "./reasoning";
+import { _debugActiveThemeScopeCount } from "./_theme-scope-store";
 
 const CODE_MARKDOWN = "```js\nconst a = 1;\n```";
 // `MarkdownView` re-maps `code` onto `ProseInlineCode`, so its Streamdown chrome
@@ -107,6 +108,28 @@ describe("Streamdown chrome microcopy (#310)", () => {
   });
 });
 
+describe("useReactiveCodePlugin shares ONE theme-scope observer (perf review §3.3)", () => {
+  it("registers a single tracked scope for many simultaneously-mounted MessageResponse instances", () => {
+    const before = _debugActiveThemeScopeCount();
+
+    const { unmount } = render(
+      <>
+        <MessageResponse>{CODE_MARKDOWN}</MessageResponse>
+        <MessageResponse>{CODE_MARKDOWN}</MessageResponse>
+        <MessageResponse>{CODE_MARKDOWN}</MessageResponse>
+      </>,
+    );
+
+    // Under the old per-hook `MutationObserver`, a message-dense conversation
+    // registered one observer PER instance; the shared store collapses every
+    // instance watching the same `<html>` scope into exactly one.
+    expect(_debugActiveThemeScopeCount()).toBe(before + 1);
+
+    unmount();
+    expect(_debugActiveThemeScopeCount()).toBe(before);
+  });
+});
+
 /**
  * #315 follow-up — the "major" carve-out: only `<CodeBlock>` had been
  * de-GitHub-ed; every fenced code block rendered through `MessageResponse`/
@@ -129,7 +152,7 @@ describe("Streamdown code-block theme (#315 follow-up)", () => {
     // (github-light's keyword is #d73a49, github-dark's is #ff7b72).
     expect(span.getAttribute("style")).toContain("--sdm-c: #133796");
     // Both dual-theme slots are pinned to the SAME active-theme color (#315
-    // follow-up design: brand-ui has three themes, not the two Shiki's
+    // follow-up design: brand-ui has more themes than the two Shiki's
     // light/dark mechanism expects), so `.dark` never resolves a different palette.
     expect(span.getAttribute("style")).toContain("--shiki-dark: #133796");
   });

package/src/task.stories.tsx

@@ -1,8 +1,18 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
 import { Task, TaskContent, TaskItem, TaskItemFile, TaskTrigger } from "./task";
-const meta = { title: "AI/Task", component: Task, parameters: { layout: "padded" } } satisfies Meta<
-  typeof Task
->;
+const meta = {
+  title: "AI/Task",
+  component: Task,
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        component:
+          "The CHAT run summary — what got done, collapsed by default so a settled transcript keeps only its focal surfaces open. The console counterpart of an agent checklist is `Terminal/TerminalTodoList`; see [Choosing between similar components](?path=/docs/docs-choosing-between-similar-components--docs). The body rides the canonical `AI/AgentTimeline` rail rather than a hand-rolled one, and what the agent intends to do BEFORE it runs is `AI/Plan`.",
+      },
+    },
+  },
+} satisfies Meta<typeof Task>;
 export default meta;
 type Story = StoryObj<typeof meta>;
 // Collapsed by default since #192; `defaultOpen` here only so the docs render