@elabs-ai/components-ai 4.0.0 → 4.1.0

package/src/composer.tsx

@@ -1,8 +1,8 @@
 "use client";
 
-import type { ComponentProps, ReactNode } from "react";
-import { ArrowUp, ChevronDown, Globe, Mic, Paperclip, Sparkles } from "lucide-react";
-import { cn, useLocale } from "@elabs-ai/components-ui";
+import { useCallback, useRef, useState, type ComponentProps, type ReactNode } from "react";
+import { ArrowUp, Mic, Paperclip, Sparkles } from "lucide-react";
+import { cn, Kbd, useLocale } from "@elabs-ai/components-ui";
 
 import {
   PromptInput,
@@ -14,8 +14,54 @@ import {
   PromptInputTools,
   type PromptInputProps,
 } from "./prompt-input";
+import { PromptInputEffort, type PromptInputEffortProps } from "./prompt-input-effort";
+import { PromptInputMode, type PromptInputModeProps } from "./prompt-input-mode";
+import {
+  PromptInputSlash,
+  PromptInputSlashTextarea,
+  type PromptInputSlashProps,
+} from "./prompt-input-slash";
 import { Suggestion, Suggestions } from "./suggestion";
 
+/**
+ * The slice of `PromptInputModeProps` a `Composer` owns — the vocabulary and
+ * the controlled/uncontrolled seam, never the DOM props of the wrapper div.
+ *
+ * `defaultValue` is deliberately absent: `PromptInputMode` has no uncontrolled
+ * initial-value seam (its uncontrolled default is `modes[0]`), and the
+ * `defaultValue` it inherits from `HTMLAttributes<HTMLDivElement>` is the DOM
+ * attribute, which would type-check and then do nothing. Omit `value` for the
+ * uncontrolled default; pass `value` + `onValueChange` to drive it.
+ */
+export type ComposerModeProps = Pick<
+  PromptInputModeProps,
+  "modes" | "value" | "onValueChange" | "aria-label"
+>;
+
+/**
+ * The slice of `PromptInputEffortProps` a `Composer` owns. `aria-label` stays
+ * REQUIRED, exactly as on the primitive: the name of the scale ("Reasoning
+ * effort", "Thinking budget") is as much the consumer's vocabulary as its
+ * levels are, so `Composer` has no default to invent either. `defaultValue` is
+ * absent for the same reason it is on `ComposerModeProps`.
+ */
+export type ComposerEffortProps = Pick<
+  PromptInputEffortProps,
+  "levels" | "value" | "onValueChange" | "aria-label"
+>;
+
+/**
+ * One shortcut-hint row entry: the physical key(s) plus what they do, shown
+ * as a `Kbd` chip beside a plain-text label — never inside a control's own
+ * name (see `ComposerProps.shortcuts`).
+ */
+export interface ComposerShortcut {
+  /** Rendered inside a `Kbd` chip, e.g. `"Enter"`, `"Shift+Enter"`. */
+  keys: string;
+  /** What the key does, in a word or two, e.g. `"send"`, `"newline"`. */
+  label: string;
+}
+
 export interface ComposerProps {
   /** Submit handler — receives the assembled message (text + attachments). */
   onSubmit?: PromptInputProps["onSubmit"];
@@ -27,18 +73,72 @@ export interface ComposerProps {
    * `null` to hide the strip entirely.
    */
   status?: ReactNode;
-  /** Model-selector pill label. Default `"Claude Opus 4"`; pass `null` to hide it. */
-  model?: ReactNode;
   /**
-   * Override the left-hand tool cluster (attach + model pill) — e.g. to add a
-   * web-search or connect-data control. Render `PromptInputButton`s /
-   * `PromptInputActionMenu` here; when set, `showAttach`/`model` are ignored.
+   * The model control, rendered first in the tools cluster after `attach`.
+   * Pass a `<ModelPicker>` from `@elabs-ai/components-ui` (it is sized to sit
+   * in a composer footer) — or anything else. Default: nothing renders.
+   *
+   * This replaces the old `model` prop, which rendered a static, non-interactive
+   * pill defaulted to a hard-coded model name. A composer that shows a model
+   * name it cannot change is a lie about what the control does; the slot now
+   * takes the real picker instead.
+   */
+  modelPicker?: ReactNode;
+  /**
+   * App-defined operating mode control — renders a `PromptInputMode` in the
+   * tools cluster. Omitted, nothing renders. `brand-ui` ships no mode
+   * vocabulary: `modes` is entirely yours.
+   */
+  mode?: ComposerModeProps;
+  /**
+   * Ordered reasoning-effort control — renders a `PromptInputEffort` in the
+   * tools cluster. Omitted, nothing renders. `levels` is ordered low → high
+   * and is entirely yours; `aria-label` names the scale.
+   */
+  effort?: ComposerEffortProps;
+  /**
+   * Slash-command palette. When set (and non-empty) the textarea becomes a
+   * `PromptInputSlashTextarea` wrapped in a `PromptInputSlash`, so typing `/`
+   * at the start of a line opens a filtered command list — nothing else about
+   * the composer changes.
+   *
+   * Note this makes the textarea REACT-CONTROLLED (the palette needs to read
+   * and splice the text), which is why `Composer` clears its own copy of the
+   * text on submit: `PromptInput`'s `form.reset()` reaches the DOM node, not
+   * React state.
+   */
+  slashCommands?: PromptInputSlashProps["commands"];
+  /** Fires with the chosen slash command (alongside the text splice). */
+  onSlashCommand?: PromptInputSlashProps["onSelect"];
+  /**
+   * Override the DEFAULT tool buttons (today: the attach button) — e.g. to add
+   * a web-search or connect-data control. Render `PromptInputButton`s /
+   * `PromptInputActionMenu` here; when set, `showAttach` is ignored.
+   *
+   * The explicit `modelPicker` / `mode` / `effort` slots are NOT part of this
+   * override — they render after whatever this puts in the cluster, so passing
+   * `tools` can never silently swallow a control you asked for by name.
    */
   tools?: ReactNode;
   /** Send-button state, forwarded to `PromptInputSubmit` (ready/submitted/streaming/error). */
   sendStatus?: ComponentProps<typeof PromptInputSubmit>["status"];
   /** Stop handler used while the send button shows the generating state. */
   onStop?: ComponentProps<typeof PromptInputSubmit>["onStop"];
+  /**
+   * Keyboard-shortcut hints shown as a row beneath the input well — plain
+   * `Kbd` + label pairs, e.g. `[{ keys: "Enter", label: "send" }]`. Omitted,
+   * nothing renders (opt-in, like every other Composer slot); the row is
+   * never invented, since the real bindings are the host app's.
+   */
+  shortcuts?: ComposerShortcut[];
+  /**
+   * A second, busy-only hint appended to `shortcuts` (#107) — shown ONLY
+   * once the composer is actually generating (`sendStatus` is `"submitted"`
+   * or `"streaming"`) AND a real `onStop` handler is set, so the hint never
+   * describes an affordance that isn't there. Mirrors
+   * `TerminalComposer`'s `canCancel = busy && Boolean(onStop)` shape.
+   */
+  cancelShortcut?: ComposerShortcut;
   /**
    * Extra props spread onto the send button — `disabled`, `aria-label`,
    * `variant`, `id`, `className`. `status` and `onStop` are excluded because
@@ -54,7 +154,8 @@ export interface ComposerProps {
    * user's text destroyed, with nothing to restore from. Disabling the control
    * is what actually prevents it: `PromptInputTextarea`'s Enter handler checks
    * `submitControl?.disabled` and bails before `requestSubmit()`, so the Enter
-   * path is closed too, not just the click.
+   * path is closed too, not just the click. It holds with a slash palette open
+   * as well — the palette's own Enter handling only ever inserts a command.
    *
    * Leave it UNSET rather than passing `false` when you have no opinion —
    * `PromptInputSubmit` resolves `disabled ?? autoDisabled`, so a literal
@@ -88,9 +189,9 @@ export interface ComposerProps {
  * Composer — the standard brand-ui AI chat input.
  *
  * A rounded two-tone "double card": a status strip wrapping a recessed
- * `PromptInput` well (sharp top, theme-rounded bottom), a model pill, voice,
- * and a circular send. Built on the real `PromptInput`, so it drops into a
- * `ChatShell` footer or stands alone as an empty-state composer. `tone`
+ * `PromptInput` well (sharp top, theme-rounded bottom), a tools cluster,
+ * voice, and a circular send. Built on the real `PromptInput`, so it drops
+ * into a `ChatShell` footer or stands alone as an empty-state composer. `tone`
  * (default `"surface"`, unchanged) picks the arrangement: `"surface"` keeps
  * the original outer `bg-card` frame around the standard muted well;
  * `"card"` (#254) swaps to an outer `bg-surface-muted` frame around a
@@ -99,18 +200,30 @@ export interface ComposerProps {
  * `tone` prop doc on `PromptInput`. Semantic tokens only; theme-aware radii
  * (`rounded-xl` frame / `rounded-b-lg` well); reads in every theme.
  *
- * This is the canonical chat input — reach for it instead of hand-rolling a
- * `PromptInput` footer.
+ * **Composer is the chat input. Every control the `PromptInput` family ships
+ * is reachable from a `Composer` prop; drop to `PromptInput` only for a
+ * bespoke shell.** `modelPicker`, `mode`, `effort` and `slashCommands` are the
+ * four slots that make that true — they render `ModelPicker`,
+ * `PromptInputMode`, `PromptInputEffort` and `PromptInputSlash` respectively,
+ * in the footer order `attach · modelPicker · mode · effort │ voice · send`
+ * (the same left-to-right arrangement `TerminalComposer` uses, so the chat and
+ * console skins agree).
  */
 export function Composer({
   onSubmit,
   placeholder,
   status = "Awaiting your input",
-  model = "Claude Opus 4",
+  modelPicker,
+  mode,
+  effort,
+  slashCommands,
+  onSlashCommand,
   tools,
   sendStatus,
   onStop,
   submitProps,
+  shortcuts,
+  cancelShortcut,
   suggestions,
   onSuggestionClick,
   showVoice = true,
@@ -120,6 +233,38 @@ export function Composer({
 }: ComposerProps) {
   const { t } = useLocale();
 
+  // Only read when `slashCommands` is set — the palette needs the live text and
+  // a handle on the field to do its caret math. Without it the textarea stays
+  // uncontrolled, exactly as before.
+  const textareaRef = useRef<HTMLTextAreaElement>(null);
+  const [text, setText] = useState("");
+  const hasSlash = slashCommands !== undefined && slashCommands.length > 0;
+
+  // #107: "Composer shortcut hints change with a busy state" — derived from
+  // the existing canonical `sendStatus`, never a second boolean prop. The
+  // cancel hint only ever joins the row once there is a real Stop affordance
+  // it can describe (mirrors `TerminalComposer`'s `canCancel` derivation).
+  const busy = sendStatus === "submitted" || sendStatus === "streaming";
+  const canCancel = busy && Boolean(onStop);
+  const allShortcuts = [
+    ...(shortcuts ?? []),
+    ...(canCancel && cancelShortcut ? [cancelShortcut] : []),
+  ];
+
+  const handleSubmit = useCallback<PromptInputProps["onSubmit"]>(
+    (message, event) => {
+      // `PromptInput.handleSubmit` calls `form.reset()`, which clears the DOM
+      // node but cannot touch React state — so the slash-mode textarea would
+      // keep rendering the sent text straight back. Clearing here is a no-op in
+      // the uncontrolled (non-slash) arrangement.
+      setText("");
+      return onSubmit?.(message, event);
+    },
+    [onSubmit],
+  );
+
+  const resolvedPlaceholder = placeholder ?? t("ai.composer.placeholder");
+
   return (
     <div className="w-full">
       <div
@@ -139,33 +284,46 @@ export function Composer({
 
         {/* Inner well — sharp top (nests under the strip), theme-rounded bottom. */}
         <PromptInput
-          onSubmit={onSubmit ?? (() => undefined)}
+          onSubmit={handleSubmit}
           surfaceClassName="rounded-t-none rounded-b-lg"
           tone={tone}
         >
           <PromptInputBody>
-            <PromptInputTextarea placeholder={placeholder ?? t("ai.composer.placeholder")} />
+            {hasSlash && slashCommands ? (
+              <PromptInputSlash
+                commands={slashCommands}
+                value={text}
+                textareaRef={textareaRef}
+                onValueChange={(next) => setText(next.text)}
+                onSelect={onSlashCommand}
+              >
+                {/* No `ref` here on purpose: PromptInputSlashTextarea merges the
+                    palette's own `textareaRef` in for us. */}
+                <PromptInputSlashTextarea
+                  value={text}
+                  onChange={(event) => setText(event.target.value)}
+                  placeholder={resolvedPlaceholder}
+                />
+              </PromptInputSlash>
+            ) : (
+              <PromptInputTextarea placeholder={resolvedPlaceholder} />
+            )}
           </PromptInputBody>
           <PromptInputFooter>
-            <PromptInputTools>
-              {tools ?? (
-                <>
-                  {showAttach ? (
-                    <PromptInputButton tooltip="Attach files">
-                      <Paperclip className="size-4" />
-                    </PromptInputButton>
-                  ) : null}
-                  {model != null ? (
-                    <PromptInputButton variant="ghost" className="gap-1.5 rounded-full">
-                      <Globe className="size-4" />
-                      <span>{model}</span>
-                      <ChevronDown className="size-4 opacity-60" />
-                    </PromptInputButton>
-                  ) : null}
-                </>
-              )}
+            {/* `flex-wrap` so a full cluster (attach + picker + mode + effort)
+                wraps instead of overflowing a narrow composer. */}
+            <PromptInputTools className="flex-wrap gap-y-1">
+              {tools ??
+                (showAttach ? (
+                  <PromptInputButton tooltip="Attach files">
+                    <Paperclip className="size-4" />
+                  </PromptInputButton>
+                ) : null)}
+              {modelPicker}
+              {mode ? <PromptInputMode {...mode} /> : null}
+              {effort ? <PromptInputEffort {...effort} /> : null}
             </PromptInputTools>
-            <div className="flex items-center gap-1">
+            <div className="flex shrink-0 items-center gap-1">
               {showVoice ? (
                 <PromptInputButton tooltip="Voice">
                   <Mic className="size-4" />
@@ -188,6 +346,30 @@ export function Composer({
             </div>
           </PromptInputFooter>
         </PromptInput>
+
+        {/* #107: the hint row itself — plain SIBLING `Kbd` + label pairs, never
+            nested inside `PromptInputSubmit` (which already names itself via its
+            own `aria-label`), so the row cannot pollute any control's accessible
+            name (the #153-style trap). */}
+        {allShortcuts.length > 0 ? (
+          <div
+            className="flex flex-wrap items-center gap-3 px-3 pt-1.5 text-meta text-muted-foreground"
+            data-slot="composer-shortcuts"
+          >
+            {allShortcuts.map((shortcut, index) => (
+              <span
+                className="inline-flex items-center gap-1.5"
+                // Shortcut rows are a fixed, non-reorderable list per render —
+                // `keys` alone isn't guaranteed unique (a caller could offer the
+                // same key for two purposes), so index is a stable, honest key.
+                key={index}
+              >
+                <Kbd>{shortcut.keys}</Kbd>
+                <span>{shortcut.label}</span>
+              </span>
+            ))}
+          </div>
+        ) : null}
       </div>
 
       {suggestions && suggestions.length > 0 ? (

package/src/confirmation.stories.tsx

@@ -1,4 +1,6 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, fn } from "storybook/test";
+import { type ApprovalOption } from "@elabs-ai/components-ui";
 import {
   ApprovalCard,
   ApprovalCardAccepted,
@@ -6,15 +8,26 @@ import {
   ApprovalCardApprove,
   ApprovalCardDeny,
   ApprovalCardDescription,
+  ApprovalCardOptions,
+  ApprovalCardReason,
   ApprovalCardRejected,
   ApprovalCardRequest,
+  ApprovalCardTarget,
   ApprovalCardTitle,
 } from "./confirmation";
 const meta = {
   title: "AI/ApprovalCard",
   component: ApprovalCard,
   tags: ["autodocs"],
-  parameters: { layout: "padded" },
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        component:
+          "The CHAT approval gate; the console skin is `Terminal/TerminalPermission`, and both read the same `ApprovalScope` / `ApprovalOption` model promoted into `@elabs-ai/components-ui` — see [Choosing between similar components](?path=/docs/docs-choosing-between-similar-components--docs). Pending is the attention treatment: a warning wash plus a hue-independent structural rail and a lift, never colour alone.",
+      },
+    },
+  },
 } satisfies Meta<typeof ApprovalCard>;
 export default meta;
 type Story = StoryObj<typeof meta>;
@@ -59,3 +72,61 @@ export const Denied: Story = {
     </ApprovalCard>
   ),
 };
+
+// N-option, scoped decision (#103) — real coding-agent permission prompts are
+// rarely a plain yes/no. `ApprovalCardTarget` previews WHAT is being
+// approved; `ApprovalCardOptions` renders the scoped choices through a real
+// Radix radiogroup; `ApprovalCardReason` carries an optional explanation that
+// travels with whichever option is chosen.
+const scopedOptions: ApprovalOption[] = [
+  { id: "once", label: "Yes", scope: "once" },
+  {
+    id: "session",
+    label: "Yes, and keep approving this command for the session",
+    scope: "session",
+  },
+  { id: "deny", label: "No", description: "Denies the deploy.", scope: "deny" },
+];
+
+export const ScopedOptions: Story = {
+  render: () => (
+    <ApprovalCard approval={{ id: "call-2" }} state="approval-requested">
+      <ApprovalCardRequest>
+        <ApprovalCardTitle>Run the production deploy script?</ApprovalCardTitle>
+        <ApprovalCardTarget>
+          <code>./scripts/deploy.sh --env production</code>
+        </ApprovalCardTarget>
+        <ApprovalCardReason />
+        <ApprovalCardOptions options={scopedOptions} />
+      </ApprovalCardRequest>
+    </ApprovalCard>
+  ),
+};
+
+const scopedOptionsOnConfirm = fn();
+
+// Types a reason FIRST, then chooses "No" — `ApprovalCardOptions` reports the
+// chosen option together with whatever reason text is already held by the
+// sibling `ApprovalCardReason` at the moment the option is selected.
+export const ScopedOptionsDenyWithReason: Story = {
+  render: () => (
+    <ApprovalCard approval={{ id: "call-3" }} state="approval-requested">
+      <ApprovalCardRequest>
+        <ApprovalCardTitle>Run the production deploy script?</ApprovalCardTitle>
+        <ApprovalCardTarget>
+          <code>./scripts/deploy.sh --env production</code>
+        </ApprovalCardTarget>
+        <ApprovalCardReason />
+        <ApprovalCardOptions options={scopedOptions} onConfirm={scopedOptionsOnConfirm} />
+      </ApprovalCardRequest>
+    </ApprovalCard>
+  ),
+  play: async ({ canvas, userEvent }) => {
+    await userEvent.type(canvas.getByRole("textbox"), "Not ready for production yet");
+    await userEvent.click(canvas.getByRole("radio", { name: /^no/i }));
+    await expect(scopedOptionsOnConfirm).toHaveBeenCalledWith(
+      scopedOptions[2],
+      "Not ready for production yet",
+    );
+  },
+};

package/src/confirmation.test.tsx

@@ -1,12 +1,18 @@
-import { describe, expect, it } from "vitest";
-import { render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { type ApprovalOption } from "@elabs-ai/components-ui";
+import * as confirmation from "./confirmation";
 import {
   ApprovalCard,
   ApprovalCardActions,
   ApprovalCardApprove,
   ApprovalCardDeny,
   ApprovalCardDescription,
+  ApprovalCardOptions,
+  ApprovalCardReason,
   ApprovalCardRequest,
+  ApprovalCardTarget,
   ApprovalCardTitle,
   Confirmation,
   ConfirmationAccepted,
@@ -134,3 +140,211 @@ describe("ApprovalCard alias", () => {
     expect(screen.getByText("Approve").className).toContain("bg-primary");
   });
 });
+
+/**
+ * The `Confirmation*` family is a CLOSED compatibility surface mirroring the
+ * AI-Elements shape (docs/decisions/2026-09-01-brainless-adoption-architecture.md § 4).
+ * New parts are `ApprovalCard*` only. Adding a name here is a decision, not a fix.
+ */
+const FROZEN_CONFIRMATION_EXPORTS = [
+  "Confirmation",
+  "ConfirmationTitle",
+  "ConfirmationDescription",
+  "ConfirmationRequest",
+  "ConfirmationAccepted",
+  "ConfirmationRejected",
+  "ConfirmationActions",
+  "ConfirmationAction",
+  "ConfirmationApprove",
+  "ConfirmationDeny",
+].sort();
+
+it("does not grow the Confirmation compatibility family", () => {
+  const actual = Object.keys(confirmation)
+    .filter((k) => k.startsWith("Confirmation"))
+    .sort();
+  expect(actual).toEqual(FROZEN_CONFIRMATION_EXPORTS);
+});
+
+describe("Confirmation binary preset is unaffected by the N-option API (#103)", () => {
+  it("still renders exactly two actions and the same rail class with no `options` prop", () => {
+    render(
+      <Confirmation state="approval-requested" approval={{ id: "t" }}>
+        <ConfirmationRequest>
+          <ConfirmationTitle>Proceed?</ConfirmationTitle>
+          <ConfirmationActions>
+            <ConfirmationDeny>Deny</ConfirmationDeny>
+            <ConfirmationApprove>Approve</ConfirmationApprove>
+          </ConfirmationActions>
+        </ConfirmationRequest>
+      </Confirmation>,
+    );
+    expect(screen.getAllByRole("button")).toHaveLength(2);
+    expect(screen.getByRole("group").className).toContain("border-s-border-strong");
+    expect(screen.queryByRole("radiogroup")).not.toBeInTheDocument();
+    expect(screen.queryByRole("textbox")).not.toBeInTheDocument();
+  });
+});
+
+describe("ApprovalCardOptions (#103) — N-option, scoped decision", () => {
+  const options: ApprovalOption[] = [
+    { id: "once", label: "Yes", scope: "once" },
+    { id: "session", label: "Yes, and don't ask again this session", scope: "session" },
+    { id: "deny", label: "No", description: "Denies this action.", scope: "deny" },
+  ];
+
+  it("renders a real radiogroup via Radix, never a hand-rolled roving group", () => {
+    render(
+      <Confirmation state="approval-requested" approval={{ id: "t" }}>
+        <ConfirmationRequest>
+          <ConfirmationTitle>Run the deploy script?</ConfirmationTitle>
+          <ApprovalCardOptions options={options} />
+        </ConfirmationRequest>
+      </Confirmation>,
+    );
+    expect(screen.getByRole("radiogroup")).toBeInTheDocument();
+    expect(screen.getAllByRole("radio")).toHaveLength(3);
+  });
+
+  it("ArrowDown from the last option wraps to the first, and the selected option is reported to onConfirm", async () => {
+    const onConfirm = vi.fn();
+    render(
+      <Confirmation state="approval-requested" approval={{ id: "t" }}>
+        <ConfirmationRequest>
+          <ConfirmationTitle>Run the deploy script?</ConfirmationTitle>
+          <ApprovalCardOptions options={options} onConfirm={onConfirm} />
+        </ConfirmationRequest>
+      </Confirmation>,
+    );
+
+    const radios = screen.getAllByRole("radio");
+    const [firstRadio, , lastRadio] = radios;
+    lastRadio!.focus();
+    await userEvent.keyboard("{ArrowDown}");
+
+    // Radix's `RovingFocusGroup` wraps focus from the last item back to the
+    // first — this is the roving-tabindex behavior we get for free by using
+    // Radix instead of a hand-rolled `parentElement.children[i]` walk.
+    expect(firstRadio).toHaveFocus();
+    // Committing a focused native radio via Space is standard browser
+    // behavior (independent of Radix's own auto-select-on-arrow-move, which
+    // relies on a real document-level focus/click ordering that jsdom does
+    // not reproduce faithfully). This still proves the acceptance criterion:
+    // the option focus wrapped to is the one reported to onConfirm.
+    await userEvent.keyboard(" ");
+
+    await waitFor(() => expect(firstRadio).toBeChecked());
+    expect(onConfirm).toHaveBeenLastCalledWith(options[0], undefined);
+  });
+
+  it("a denial with typed reason text calls onConfirm with both the option and the reason", async () => {
+    const onConfirm = vi.fn();
+    render(
+      <Confirmation state="approval-requested" approval={{ id: "t" }}>
+        <ConfirmationRequest>
+          <ConfirmationTitle>Delete the release branch?</ConfirmationTitle>
+          <ApprovalCardReason />
+          <ApprovalCardOptions options={options} onConfirm={onConfirm} />
+        </ConfirmationRequest>
+      </Confirmation>,
+    );
+
+    await userEvent.type(screen.getByRole("textbox"), "Not ready yet");
+    await userEvent.click(screen.getByRole("radio", { name: /^no/i }));
+
+    expect(onConfirm).toHaveBeenCalledWith(options[2], "Not ready yet");
+  });
+
+  it("falls back to a scope-derived description when the caller supplies none — never colour/data-* alone", () => {
+    render(
+      <Confirmation state="approval-requested" approval={{ id: "t" }}>
+        <ConfirmationRequest>
+          <ConfirmationTitle>Install dependencies?</ConfirmationTitle>
+          <ApprovalCardOptions
+            options={[{ id: "always", label: "Yes, always", scope: "always" }]}
+          />
+        </ConfirmationRequest>
+      </Confirmation>,
+    );
+    // No LocaleProvider is mounted, so `t()` falls back to the shipped English
+    // default — real, visible text tied to the option via `aria-describedby`,
+    // not a colour or a bare `data-*` attribute. Asserting the SENTENCE (not
+    // the key) is what proves the central catalogue actually carries it.
+    const radio = screen.getByRole("radio", { name: "Yes, always" });
+    const describedBy = radio.getAttribute("aria-describedby");
+    expect(describedBy).toBeTruthy();
+    expect(document.getElementById(describedBy!)?.textContent).toBe(
+      "Applies to actions like this from now on.",
+    );
+  });
+
+  it("prefers a caller-supplied description over the derived scope text", () => {
+    render(
+      <Confirmation state="approval-requested" approval={{ id: "t" }}>
+        <ConfirmationRequest>
+          <ConfirmationTitle>Install dependencies?</ConfirmationTitle>
+          <ApprovalCardOptions options={options} />
+        </ConfirmationRequest>
+      </Confirmation>,
+    );
+    expect(screen.getByText("Denies this action.")).toBeInTheDocument();
+  });
+
+  it("is uncontrolled by default and controlled when `value` is supplied", async () => {
+    const onValueChange = vi.fn();
+    const { rerender } = render(
+      <Confirmation state="approval-requested" approval={{ id: "t" }}>
+        <ConfirmationRequest>
+          <ConfirmationTitle>Run the deploy script?</ConfirmationTitle>
+          <ApprovalCardOptions options={options} value="once" onValueChange={onValueChange} />
+        </ConfirmationRequest>
+      </Confirmation>,
+    );
+    const sessionRadio = screen.getByRole("radio", {
+      name: "Yes, and don't ask again this session",
+    });
+    await userEvent.click(sessionRadio);
+    expect(onValueChange).toHaveBeenCalledWith("session");
+    // Controlled: the caller did not update `value` in response, so the
+    // checked state stays pinned to the `value` prop, not the click.
+    expect(screen.getByRole("radio", { name: "Yes" })).toBeChecked();
+    expect(sessionRadio).not.toBeChecked();
+
+    rerender(
+      <Confirmation state="approval-requested" approval={{ id: "t" }}>
+        <ConfirmationRequest>
+          <ConfirmationTitle>Run the deploy script?</ConfirmationTitle>
+          <ApprovalCardOptions options={options} value="session" onValueChange={onValueChange} />
+        </ConfirmationRequest>
+      </Confirmation>,
+    );
+    expect(
+      screen.getByRole("radio", { name: "Yes, and don't ask again this session" }),
+    ).toBeChecked();
+  });
+});
+
+describe("ApprovalCardTarget (#103)", () => {
+  it("accepts arbitrary children — e.g. a command or diff preview", () => {
+    render(
+      <Confirmation state="approval-requested" approval={{ id: "t" }}>
+        <ConfirmationRequest>
+          <ConfirmationTitle>Apply this change?</ConfirmationTitle>
+          <ApprovalCardTarget>
+            <pre>rm -rf build/</pre>
+          </ApprovalCardTarget>
+        </ConfirmationRequest>
+      </Confirmation>,
+    );
+    expect(screen.getByText("rm -rf build/")).toBeInTheDocument();
+  });
+
+  it("stays visible after the decision resolves (not gated by state)", () => {
+    render(
+      <Confirmation state="approval-responded" approval={{ id: "t", approved: true }}>
+        <ApprovalCardTarget>rm -rf build/</ApprovalCardTarget>
+      </Confirmation>,
+    );
+    expect(screen.getByText("rm -rf build/")).toBeInTheDocument();
+  });
+});