@elabs-ai/components-ai 4.0.0 → 4.2.0

package/src/confirmation.tsx

@@ -1,11 +1,24 @@
 "use client";
 
-import { Alert, AlertDescription, AlertTitle, StatusBadge } from "@elabs-ai/components-ui";
+import {
+  Alert,
+  AlertDescription,
+  AlertTitle,
+  APPROVAL_SCOPE_DESCRIPTION_KEYS,
+  Kbd,
+  Label,
+  RadioGroup,
+  RadioGroupItem,
+  StatusBadge,
+  Textarea,
+  useLocale,
+  type ApprovalOption,
+} from "@elabs-ai/components-ui";
 import { Button } from "@elabs-ai/components-ui";
 import { cn } from "@elabs-ai/components-ui/lib/cn";
 import type { ToolUIPart } from "ai";
 import type { ComponentProps, ReactNode } from "react";
-import { createContext, useContext, useId, useMemo } from "react";
+import { createContext, forwardRef, useContext, useId, useMemo, useState } from "react";
 
 type ToolUIPartApproval =
   | {
@@ -35,6 +48,15 @@ interface ConfirmationContextValue {
   state: ToolUIPart["state"];
   /** Default id wired from the card's `aria-labelledby` to `ConfirmationTitle`. */
   titleId: string;
+  /**
+   * Shared draft reason text (#103) — written by `ApprovalCardReason`, read by
+   * `ApprovalCardOptions` at the moment a decision commits, so a typed
+   * explanation reaches `onConfirm`'s second argument without threading a
+   * prop between two sibling compound parts. Unused by the pre-existing
+   * binary `Confirmation*` parts, so their rendered output is unaffected.
+   */
+  reason: string;
+  setReason: (reason: string) => void;
 }
 
 const ConfirmationContext = createContext<ConfirmationContextValue | null>(null);
@@ -64,7 +86,11 @@ export const Confirmation = ({
   ...props
 }: ConfirmationProps) => {
   const titleId = useId();
-  const contextValue = useMemo(() => ({ approval, state, titleId }), [approval, state, titleId]);
+  const [reason, setReason] = useState("");
+  const contextValue = useMemo(
+    () => ({ approval, state, titleId, reason, setReason }),
+    [approval, state, titleId, reason],
+  );
 
   if (!approval || state === "input-streaming" || state === "input-available") {
     return null;
@@ -225,7 +251,7 @@ export const ConfirmationActions = ({ className, ...props }: ConfirmationActions
 export type ConfirmationActionProps = ComponentProps<typeof Button>;
 
 export const ConfirmationAction = ({ className, ...props }: ConfirmationActionProps) => (
-  <Button className={cn("h-8 px-3 text-sm", className)} type="button" {...props} />
+  <Button className={cn("h-8 px-3 text-body", className)} type="button" {...props} />
 );
 
 export type ConfirmationApproveProps = ConfirmationActionProps;
@@ -250,6 +276,12 @@ export const ConfirmationDeny = (props: ConfirmationDenyProps) => (
  * interaction (research 11 §B.3). Same components, clearer name; the
  * `Confirmation*` exports stay for the AI-Elements-shaped API (non-breaking).
  * New code reaches for `ApprovalCard`.
+ *
+ * The `Confirmation*` family below is CLOSED — frozen at exactly the ten
+ * names aliased here. New parts (#103 and beyond) are declared as real
+ * `ApprovalCard*` implementations, never added to this alias block. See
+ * `docs/decisions/2026-09-01-brainless-adoption-architecture.md` § 4 and the
+ * `FROZEN_CONFIRMATION_EXPORTS` lock in `confirmation.test.tsx`.
  */
 export const ApprovalCard = Confirmation;
 export type ApprovalCardProps = ConfirmationProps;
@@ -271,3 +303,231 @@ export const ApprovalCardApprove = ConfirmationApprove;
 export type ApprovalCardApproveProps = ConfirmationApproveProps;
 export const ApprovalCardDeny = ConfirmationDeny;
 export type ApprovalCardDenyProps = ConfirmationDenyProps;
+
+/*
+ * ---------------------------------------------------------------------------
+ * N-option, scoped approval (#103)
+ * ---------------------------------------------------------------------------
+ * Real coding-agent permission prompts are rarely a plain yes/no — they ask
+ * an N-option question whose options encode SCOPE: "Yes", "Yes, and don't ask
+ * again this session", "No, and tell the agent what to do instead". The
+ * binary `Confirmation`/`ApprovalCard` pair above cannot express the middle
+ * option; these three parts extend it additively, composed as CHILDREN of the
+ * existing card (`ApprovalCard` / `ApprovalCardRequest`), never as a
+ * replacement for it. Every new export here is a real `ApprovalCard*`
+ * implementation — see the closed-family note above the alias block.
+ *
+ * Vocabulary note: this is the PER-CALL decision surface ("may I run this
+ * command?"). `PermissionModeSelect` (#104) is the separate, standing POLICY
+ * surface ("how much may you do without asking?") — the two compose rather
+ * than merge into one boolean-flagged component, per
+ * `.claude/rules/component-api.md` ("Avoid boolean-prop proliferation").
+ */
+
+/**
+ * `ApprovalScope`, `ApprovalOption` and `APPROVAL_SCOPE_DESCRIPTION_KEYS`
+ * moved to `@elabs-ai/components-ui` (`lib/approval-option.ts`) — the
+ * terminal CLI look-alike family's own permission row (issue #117) reuses
+ * the same model, and `@elabs-ai/components-ai`/`@elabs-ai/components-terminal`
+ * are layer-2 DAG siblings that may not import each other (T0; see
+ * docs/decisions/2026-09-01-brainless-adoption-architecture.md § 4). Imported
+ * above.
+ */
+
+export interface ApprovalCardOptionsProps extends ComponentProps<"div"> {
+  options: ApprovalOption[];
+  value?: string;
+  defaultValue?: string;
+  onValueChange?: (id: string) => void;
+  /**
+   * Fires when an option is selected — by click, or by ANY keyboard move
+   * within the radio group (Home/End/arrow keys select immediately, per the
+   * native/ARIA radiogroup pattern Radix implements; there is no separate
+   * "highlight vs commit" step). Reports the full resolved `ApprovalOption`
+   * plus whatever reason text is currently held by a sibling
+   * `ApprovalCardReason` — type a reason BEFORE choosing an option to have it
+   * included in this call.
+   */
+  onConfirm?: (option: ApprovalOption, reason?: string) => void;
+}
+
+/**
+ * ApprovalCardOptions — the N-option, scoped decision (#103). Renders through
+ * `@elabs-ai/components-ui`'s `RadioGroup` (Radix) for roving focus, arrow-key
+ * wrap, Home/End and announcement — never a hand-rolled
+ * `parentElement.children[i]` focus walk. Composed inside `ApprovalCardRequest`,
+ * alongside the existing `ApprovalCardTitle`/`ApprovalCardDescription`.
+ */
+export const ApprovalCardOptions = forwardRef<HTMLDivElement, ApprovalCardOptionsProps>(
+  function ApprovalCardOptions(
+    {
+      options,
+      value,
+      defaultValue,
+      onValueChange,
+      onConfirm,
+      className,
+      dir,
+      "aria-labelledby": ariaLabelledBy,
+      ...props
+    },
+    ref,
+  ) {
+    const { t } = useLocale();
+    const { titleId, reason } = useConfirmation();
+    const baseId = useId();
+
+    // Controlled/uncontrolled mirrors the platform (and `PermissionModeSelect`,
+    // #104): `value`/`onValueChange` for a controlled caller, `defaultValue`
+    // for an uncontrolled starting point — Radix's own `RadioGroup` already
+    // implements both correctly. Hand-rolling a parallel `internalValue`
+    // state here and always passing a (possibly `undefined`) `value` down
+    // makes Radix's controllable-state hook see a spurious
+    // uncontrolled-to-controlled transition the first time a selection is
+    // made, which is exactly the warning this avoids.
+    const handleValueChange = (id: string) => {
+      onValueChange?.(id);
+      const option = options.find((candidate) => candidate.id === id);
+      if (option) onConfirm?.(option, reason.trim() ? reason : undefined);
+    };
+
+    return (
+      <RadioGroup
+        ref={ref}
+        // `dir` on a plain <div> is a free-form HTML string; Radix's
+        // RadioGroup narrows it to "ltr" | "rtl". Cast at this single call
+        // site, matching `PermissionModeSelect` (#104), rather than widening
+        // (and so weakening) the public prop type.
+        dir={dir as "ltr" | "rtl" | undefined}
+        defaultValue={defaultValue}
+        value={value}
+        onValueChange={handleValueChange}
+        aria-labelledby={ariaLabelledBy ?? titleId}
+        data-slot="approval-card-options"
+        className={cn("grid gap-2", className)}
+        {...props}
+      >
+        {options.map((option) => {
+          const itemId = `${baseId}-${option.id}`;
+          const descriptionId = `${itemId}-description`;
+          const description =
+            option.description ?? t(APPROVAL_SCOPE_DESCRIPTION_KEYS[option.scope]);
+
+          return (
+            <div
+              key={option.id}
+              data-slot="approval-card-option"
+              data-scope={option.scope}
+              className={cn(
+                "flex items-start gap-3 rounded-lg border border-border bg-card p-3",
+                "has-[[data-state=checked]]:border-primary",
+              )}
+            >
+              <RadioGroupItem
+                aria-describedby={descriptionId}
+                className="mt-1"
+                data-slot="approval-card-option-input"
+                id={itemId}
+                value={option.id}
+              />
+              <div className="grid flex-1 gap-1">
+                <div className="flex items-center justify-between gap-2">
+                  <Label
+                    className="text-body flex items-center gap-2 font-medium"
+                    data-slot="approval-card-option-label"
+                    htmlFor={itemId}
+                  >
+                    {option.label}
+                  </Label>
+                  {option.keyHint ? (
+                    <Kbd data-slot="approval-card-option-key-hint">{option.keyHint}</Kbd>
+                  ) : null}
+                </div>
+                <p
+                  className="text-meta text-muted-foreground"
+                  data-slot="approval-card-option-description"
+                  id={descriptionId}
+                >
+                  {description}
+                </p>
+              </div>
+            </div>
+          );
+        })}
+      </RadioGroup>
+    );
+  },
+);
+
+ApprovalCardOptions.displayName = "ApprovalCardOptions";
+
+export type ApprovalCardTargetProps = ComponentProps<"div">;
+
+/**
+ * ApprovalCardTarget — the preview slot for WHAT is being approved: a
+ * command, a path, or a richer node such as a `DiffView` (#102). Accepts
+ * arbitrary children — this file never imports `DiffView`, the composition
+ * happens entirely in the consumer's tree. Ungated by state (unlike
+ * `ApprovalCardRequest`/`Accepted`/`Rejected`): the subject of a decision
+ * stays visible after it resolves, not only while pending.
+ */
+export const ApprovalCardTarget = forwardRef<HTMLDivElement, ApprovalCardTargetProps>(
+  function ApprovalCardTarget({ className, ...props }, ref) {
+    return (
+      <div
+        ref={ref}
+        data-slot="approval-card-target"
+        className={cn("text-body rounded-md bg-muted/50 p-3", className)}
+        {...props}
+      />
+    );
+  },
+);
+
+ApprovalCardTarget.displayName = "ApprovalCardTarget";
+
+export type ApprovalCardReasonProps = Omit<
+  ComponentProps<typeof Textarea>,
+  "value" | "defaultValue" | "onChange"
+>;
+
+/**
+ * ApprovalCardReason — the deny-with-reason input, wired to the `reason`
+ * field that already exists on `ToolUIPartApproval` and was previously
+ * unreachable from the UI. Shares its value with `ApprovalCardOptions`
+ * through `Confirmation`'s own context (not a prop threaded between the two
+ * sibling parts) — type here BEFORE choosing an option to have the text
+ * included in that option's `onConfirm` call.
+ */
+export const ApprovalCardReason = forwardRef<HTMLTextAreaElement, ApprovalCardReasonProps>(
+  function ApprovalCardReason({ className, id, placeholder, ...props }, ref) {
+    const { t } = useLocale();
+    const { reason, setReason } = useConfirmation();
+    const generatedId = useId();
+    const textareaId = id ?? generatedId;
+
+    return (
+      <div className="grid gap-1.5" data-slot="approval-card-reason">
+        <Label
+          className="text-meta text-muted-foreground"
+          data-slot="approval-card-reason-label"
+          htmlFor={textareaId}
+        >
+          {t("ai.approvalCard.reasonLabel")}
+        </Label>
+        <Textarea
+          ref={ref}
+          id={textareaId}
+          placeholder={placeholder ?? t("ai.approvalCard.reasonPlaceholder")}
+          value={reason}
+          onChange={(event) => setReason(event.target.value)}
+          data-slot="approval-card-reason-input"
+          className={cn("min-h-16 text-body", className)}
+          {...props}
+        />
+      </div>
+    );
+  },
+);
+
+ApprovalCardReason.displayName = "ApprovalCardReason";

package/src/context-panel.stories.tsx

@@ -18,7 +18,15 @@ const meta = {
   title: "AI/ContextPanel",
   component: ContextPanel,
   tags: ["autodocs"],
-  parameters: { layout: "padded" },
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        component:
+          "The chat workspace’s right context RAIL: produced assets, a preview drill-in, and an always-mounted width tween so an external `ContextPanelTrigger` can drive it from anywhere inside `ContextPanelProvider`. Nothing to do with `AI/TokenUsage`, the context-WINDOW usage ring, which carried the name `Context` until it was renamed for exactly this confusion; see [Choosing between similar components](?path=/docs/docs-choosing-between-similar-components--docs). Below the mobile breakpoint the rail degrades to a right-side `Sheet` driven by the same state.",
+      },
+    },
+  },
 } satisfies Meta<typeof ContextPanel>;
 export default meta;
 type Story = StoryObj<typeof meta>;

package/src/context-panel.tsx

@@ -355,6 +355,7 @@ export const ContextPanel = forwardRef<HTMLDivElement, ContextPanelProps>(functi
 ) {
   const { state, actions, meta } = useContextPanel();
   const { panelId } = useContextPanelInternal();
+  const { t } = useLocale();
 
   const panel = useCollapsiblePanel({
     side: "right",
@@ -380,8 +381,8 @@ export const ContextPanel = forwardRef<HTMLDivElement, ContextPanelProps>(functi
           style={{ "--context-panel-width": CONTEXT_PANEL_WIDTH_MOBILE } as CSSProperties}
         >
           <SheetHeader className="sr-only">
-            <SheetTitle>Context panel</SheetTitle>
-            <SheetDescription>Displays the chat context panel.</SheetDescription>
+            <SheetTitle>{t("ai.contextPanel.title")}</SheetTitle>
+            <SheetDescription>{t("ai.contextPanel.description")}</SheetDescription>
           </SheetHeader>
           <div className="flex h-full w-full flex-col">{children}</div>
         </SheetContent>

package/src/conversation.stories.tsx

@@ -1,10 +1,19 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
-import { Conversation, ConversationContent } from "./conversation";
+import { expect, within } from "storybook/test";
+import { Conversation, ConversationContent, ConversationEmptyState } from "./conversation";
 import { Message, MessageContent } from "./message";
 const meta = {
   title: "AI/Conversation",
   component: Conversation,
-  parameters: { layout: "padded" },
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        component:
+          "The CHAT scrolling transcript region — stick-to-bottom, with a scroll-to-bottom button once the reader leaves the end. The console counterpart is `Terminal/TerminalSurface`, and the frame around either is `AI/ChatShell` or `Terminal/TerminalConsole`. See [Choosing between similar components](?path=/docs/docs-choosing-between-similar-components--docs).",
+      },
+    },
+  },
 } satisfies Meta<typeof Conversation>;
 export default meta;
 type Story = StoryObj<typeof meta>;
@@ -24,3 +33,78 @@ export const Default: Story = {
     </div>
   ),
 };
+
+/**
+ * `isStreaming` suppresses the live-region chatter while tokens are still
+ * arriving (`aria-live="off"` + `aria-busy`) — see the prop's doc on
+ * `ConversationProps` for why a `"polite"` region would otherwise announce
+ * every incoming token.
+ */
+export const Streaming: Story = {
+  render: () => (
+    <div className="flex h-72 flex-col rounded-lg border">
+      <Conversation isStreaming>
+        <ConversationContent>
+          <Message from="user">
+            <MessageContent>Summarize the deploy log.</MessageContent>
+          </Message>
+          <Message from="assistant">
+            <MessageContent>Deploying to production</MessageContent>
+          </Message>
+        </ConversationContent>
+      </Conversation>
+    </div>
+  ),
+};
+
+/**
+ * **Layout lock (#72).** With zero messages, `ConversationEmptyState` must render
+ * vertically centred in the conversation canvas — not pinned to the top with a
+ * gap of empty space below (the original bug: `ConversationContent` never grew
+ * past its shrink-wrapped content size, so the canvas's extra height sat unused
+ * below it).
+ *
+ * This can only be verified with real CSS layout (`getBoundingClientRect`), never
+ * a class-string assertion — jsdom performs no layout, and asserting a class name
+ * would have passed on the buggy `size-full` markup verbatim (`size-full` was
+ * always present; it just had nothing to fill). Per
+ * `.claude/rules/component-api.md` § "Regression locks with observable side
+ * effects", this runs in the ordinary full-suite invocation, not only isolated.
+ *
+ * We deliberately measure `ConversationEmptyState`'s OWN rendered box against the
+ * outer canvas (`role="log"`'s parent), not against `ConversationContent`'s box —
+ * the empty state is `size-full` inside `ConversationContent`, so comparing it to
+ * its immediate parent is tautological (it always exactly fills it, bug or not).
+ * Comparing against the fixed-height canvas is what actually distinguishes
+ * "pinned to the top of a tall canvas" from "filling — and centred within — the
+ * canvas".
+ */
+export const EmptyStateCentering: Story = {
+  render: () => (
+    <div className="flex h-72 flex-col rounded-lg border">
+      <Conversation>
+        <ConversationContent>
+          <ConversationEmptyState
+            title="Start the conversation"
+            description="Ask anything to begin."
+          />
+        </ConversationContent>
+      </Conversation>
+    </div>
+  ),
+  play: async ({ canvasElement }) => {
+    const log = within(canvasElement).getByRole("log");
+    const canvas = log.parentElement as HTMLElement;
+    const heading = within(canvasElement).getByRole("heading", { name: "Start the conversation" });
+    // heading (h3) -> the "space-y-1" title/description group -> ConversationEmptyState's own root div.
+    const emptyState = heading.parentElement!.parentElement as HTMLElement;
+
+    const canvasRect = canvas.getBoundingClientRect();
+    const emptyRect = emptyState.getBoundingClientRect();
+
+    const gapAbove = emptyRect.top - canvasRect.top;
+    const gapBelow = canvasRect.bottom - emptyRect.bottom;
+
+    await expect(Math.abs(gapAbove - gapBelow)).toBeLessThan(8);
+  },
+};

package/src/conversation.test.tsx

@@ -16,6 +16,7 @@ import type { UIMessage } from "ai";
 import {
   Conversation,
   ConversationContent,
+  ConversationDownload,
   ConversationEmptyState,
   messagesToMarkdown,
 } from "./conversation";
@@ -69,6 +70,46 @@ describe("Conversation — transcript region", () => {
     expect(screen.getByRole("log")).toHaveClass("extra");
     expect(screen.getByRole("log")).toHaveClass("flex-1");
   });
+
+  it('defaults to aria-live="polite" and no aria-busy (not streaming)', () => {
+    render(
+      <Conversation>
+        <ConversationContent>x</ConversationContent>
+      </Conversation>,
+    );
+    const log = screen.getByRole("log");
+    expect(log).toHaveAttribute("aria-live", "polite");
+    expect(log).not.toHaveAttribute("aria-busy");
+  });
+
+  it('suppresses aria-live and sets aria-busy while isStreaming (perf review §2 — role="log" must not announce every token)', () => {
+    render(
+      <Conversation isStreaming>
+        <ConversationContent>x</ConversationContent>
+      </Conversation>,
+    );
+    const log = screen.getByRole("log");
+    expect(log).toHaveAttribute("aria-live", "off");
+    expect(log).toHaveAttribute("aria-busy", "true");
+  });
+
+  it("returns to aria-live=polite once streaming settles, so the final content is announced", () => {
+    const { rerender } = render(
+      <Conversation isStreaming>
+        <ConversationContent>partial</ConversationContent>
+      </Conversation>,
+    );
+    expect(screen.getByRole("log")).toHaveAttribute("aria-live", "off");
+
+    rerender(
+      <Conversation isStreaming={false}>
+        <ConversationContent>final</ConversationContent>
+      </Conversation>,
+    );
+    const log = screen.getByRole("log");
+    expect(log).toHaveAttribute("aria-live", "polite");
+    expect(log).not.toHaveAttribute("aria-busy");
+  });
 });
 
 describe("ConversationEmptyState", () => {
@@ -93,6 +134,31 @@ describe("ConversationEmptyState", () => {
     expect(screen.getByText("custom")).toBeInTheDocument();
     expect(screen.queryByRole("heading", { name: "No messages yet" })).toBeNull();
   });
+
+  // API lock (#72): `actions` completes the EmptyState anatomy (illustration/icon
+  // + title + one sentence + one action, per .claude/rules/design-first.md) —
+  // without it, ConversationEmptyState could not offer a next step at all.
+  it("renders a passed actions node", () => {
+    render(<ConversationEmptyState actions={<button type="button">Ask something</button>} />);
+    expect(screen.getByRole("button", { name: "Ask something" })).toBeInTheDocument();
+  });
+
+  it("omits the actions wrapper entirely when no actions are passed", () => {
+    const { container } = render(<ConversationEmptyState />);
+    expect(container.querySelectorAll("button")).toHaveLength(0);
+  });
+});
+
+describe("ConversationDownload — accessible name (accessibility.md)", () => {
+  it("names the icon-only download control", () => {
+    render(<ConversationDownload messages={messages} />);
+    expect(screen.getByRole("button", { name: "Download conversation" })).toBeInTheDocument();
+  });
+
+  it("lets a caller override the accessible name", () => {
+    render(<ConversationDownload aria-label="Export chat" messages={messages} />);
+    expect(screen.getByRole("button", { name: "Export chat" })).toBeInTheDocument();
+  });
 });
 
 describe("messagesToMarkdown — the download serializer", () => {

package/src/conversation.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { Button, downloadBlob } from "@elabs-ai/components-ui";
+import { Button, downloadBlob, useLocale } from "@elabs-ai/components-ui";
 import { cn } from "@elabs-ai/components-ui/lib/cn";
 import type { UIMessage } from "ai";
 import { ArrowDownIcon, DownloadIcon } from "lucide-react";
@@ -8,28 +8,57 @@ import type { ComponentProps } from "react";
 import { useCallback } from "react";
 import { StickToBottom, useStickToBottomContext } from "use-stick-to-bottom";
 
-export type ConversationProps = ComponentProps<typeof StickToBottom>;
+export type ConversationProps = ComponentProps<typeof StickToBottom> & {
+  /**
+   * The assistant response is still arriving (loading-states.md
+   * `isStreaming`). `role="log"` otherwise announces every incoming token to
+   * assistive tech as it streams in — deafening. While `true`, `aria-live`
+   * is suppressed (`"off"`) and `aria-busy` is set; once streaming ends,
+   * `aria-live` returns to `"polite"` so the settled content is what
+   * actually gets announced.
+   * @default false
+   */
+  isStreaming?: boolean;
+};
 
-export const Conversation = ({ className, ...props }: ConversationProps) => (
+export const Conversation = ({ className, isStreaming = false, ...props }: ConversationProps) => (
   <StickToBottom
     className={cn("relative flex-1 overflow-y-hidden", className)}
     initial="smooth"
     resize="smooth"
     role="log"
+    aria-live={isStreaming ? "off" : "polite"}
+    aria-busy={isStreaming || undefined}
     {...props}
   />
 );
 
 export type ConversationContentProps = ComponentProps<typeof StickToBottom.Content>;
 
-export const ConversationContent = ({ className, ...props }: ConversationContentProps) => (
-  <StickToBottom.Content className={cn("flex flex-col gap-8 p-4", className)} {...props} />
+export const ConversationContent = ({
+  className,
+  scrollClassName,
+  ...props
+}: ConversationContentProps) => (
+  <StickToBottom.Content
+    // `use-stick-to-bottom` renders a scroll viewport (`scrollClassName`)
+    // wrapping a content div (`className`, via `...props`). The viewport must
+    // be a flex column so its height is a DEFINITE main size the content div
+    // can consume via `flex-1` — a bare `height:100%` on the content div
+    // can't resolve against a block-level parent whose own height is
+    // `min-height`-only (the #72 empty-state-pinned-to-the-top bug).
+    scrollClassName={cn("flex flex-col", scrollClassName)}
+    className={cn("flex flex-1 min-h-0 flex-col gap-8 p-4", className)}
+    {...props}
+  />
 );
 
 export type ConversationEmptyStateProps = ComponentProps<"div"> & {
   title?: string;
   description?: string;
   icon?: React.ReactNode;
+  /** Primary / secondary action(s) below the description (e.g. suggested prompts). */
+  actions?: React.ReactNode;
 };
 
 export const ConversationEmptyState = ({
@@ -37,6 +66,7 @@ export const ConversationEmptyState = ({
   title = "No messages yet",
   description = "Start a conversation to see messages here",
   icon,
+  actions,
   children,
   ...props
 }: ConversationEmptyStateProps) => (
@@ -51,9 +81,10 @@ export const ConversationEmptyState = ({
       <>
         {icon && <div className="text-muted-foreground">{icon}</div>}
         <div className="space-y-1">
-          <h3 className="font-medium text-sm">{title}</h3>
-          {description && <p className="text-muted-foreground text-sm">{description}</p>}
+          <h3 className="font-medium text-body">{title}</h3>
+          {description && <p className="text-muted-foreground text-body">{description}</p>}
         </div>
+        {actions ? <div className="mt-1 flex items-center gap-2">{actions}</div> : null}
       </>
     )}
   </div>
@@ -66,6 +97,7 @@ export const ConversationScrollButton = ({
   ...props
 }: ConversationScrollButtonProps) => {
   const { isAtBottom, scrollToBottom } = useStickToBottomContext();
+  const { t } = useLocale();
 
   const handleScrollToBottom = useCallback(() => {
     scrollToBottom();
@@ -75,9 +107,16 @@ export const ConversationScrollButton = ({
     !isAtBottom && (
       <Button
         className={cn(
-          "absolute bottom-4 left-[50%] translate-x-[-50%] rounded-full dark:bg-background dark:hover:bg-muted",
+          // Was `dark:bg-background dark:hover:bg-muted` — a hardcoded-dark
+          // branch invisible to any other registered theme (styling-and-tokens.md).
+          // `bg-background` already matches the `outline` variant's own default;
+          // the quieter `hover:bg-muted` (in place of `outline`'s default
+          // `hover:bg-accent`) now applies in every theme, not only the two
+          // shipped ones.
+          "absolute bottom-4 left-[50%] translate-x-[-50%] rounded-full bg-background hover:bg-muted",
           className,
         )}
+        aria-label={t("ai.turnStatus.scrollToBottom")}
         onClick={handleScrollToBottom}
         size="icon"
         type="button"
@@ -120,6 +159,7 @@ export const ConversationDownload = ({
   children,
   ...props
 }: ConversationDownloadProps) => {
+  const { t } = useLocale();
   const handleDownload = useCallback(() => {
     const markdown = messagesToMarkdown(messages, formatMessage);
     downloadBlob(new Blob([markdown], { type: "text/markdown" }), filename);
@@ -128,9 +168,12 @@ export const ConversationDownload = ({
   return (
     <Button
       className={cn(
-        "absolute top-4 end-4 rounded-full dark:bg-background dark:hover:bg-muted",
+        // See `ConversationScrollButton` — was a hardcoded-dark-only branch;
+        // `bg-background hover:bg-muted` now applies in every theme.
+        "absolute top-4 end-4 rounded-full bg-background hover:bg-muted",
         className,
       )}
+      aria-label={t("ai.conversation.download")}
       onClick={handleDownload}
       size="icon"
       type="button"