@elabs-ai/components-ai 4.0.0 → 4.1.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;
@@ -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,7 +381,7 @@ 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>
+            <SheetTitle>{t("ai.contextPanel.title")}</SheetTitle>
             <SheetDescription>Displays the chat context panel.</SheetDescription>
           </SheetHeader>
           <div className="flex h-full w-full flex-col">{children}</div>

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,55 @@ export const Default: Story = {
     </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

@@ -93,6 +93,19 @@ 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("messagesToMarkdown — the download serializer", () => {

package/src/conversation.tsx

@@ -22,14 +22,30 @@ export const Conversation = ({ className, ...props }: ConversationProps) => (
 
 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 +53,7 @@ export const ConversationEmptyState = ({
   title = "No messages yet",
   description = "Start a conversation to see messages here",
   icon,
+  actions,
   children,
   ...props
 }: ConversationEmptyStateProps) => (
@@ -54,6 +71,7 @@ export const ConversationEmptyState = ({
           <h3 className="font-medium text-sm">{title}</h3>
           {description && <p className="text-muted-foreground text-sm">{description}</p>}
         </div>
+        {actions ? <div className="mt-1 flex items-center gap-2">{actions}</div> : null}
       </>
     )}
   </div>

package/src/diff-view.stories.tsx

@@ -0,0 +1,196 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, userEvent, within } from "storybook/test";
+import { ChangeReview, type ChangeHunk, type DiffLine } from "@elabs-ai/components-ui";
+import { DiffView } from "./diff-view";
+
+const meta = {
+  title: "AI/DiffView",
+  component: DiffView,
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        component:
+          "The READ-ONLY patch renderer. Pick a diff surface by what the human is allowed " +
+          "to do with the change: reading lines of a patch → `AI/DiffView` " +
+          "(`@elabs-ai/components-ai`); accepting or rejecting per hunk → " +
+          "`AI/ChangeReview` (`@elabs-ai/components-ui`); editing both sides, side by " +
+          "side → `Editor/DiffEditor` (`@elabs-ai/components-editor`); reading a " +
+          "patch in a console transcript → `Terminal/TerminalDiffHunk` " +
+          "(`@elabs-ai/components-terminal`). See " +
+          "[Choosing between similar components](?path=/docs/docs-choosing-between-similar-components--docs). " +
+          "This view renders a `DiffLine[]` someone else computed — it never diffs, " +
+          "fetches or parses a patch itself. To put those lines behind an approve/reject " +
+          "gate, the app that depends on both packages injects one into the other: pass a " +
+          "`<DiffView>` through `ChangeReview`’s `renderHunk` render-prop or a " +
+          "hunk’s `after` slot, as the *Composed into ChangeReview (ui)* story below " +
+          "does. That seam is ratified, not unfinished — `ChangeHunk` gains no " +
+          "`lines` field and `DiffLine` never moves, because `@elabs-ai/components-ui` " +
+          "may not import `@elabs-ai/components-ai` and this view needs Shiki.",
+      },
+    },
+  },
+  tags: ["autodocs"],
+} satisfies Meta<typeof DiffView>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// A representative mix of every DiffLineType — meta headers, a hunk range, a
+// deletion, two additions and trailing context (#102 acceptance criteria).
+const SAMPLE_LINES: DiffLine[] = [
+  { type: "meta", text: "diff --git a/src/math.ts b/src/math.ts" },
+  { type: "meta", text: "index a1b2c3d..e4f5g6h 100644" },
+  { type: "meta", text: "--- a/src/math.ts" },
+  { type: "meta", text: "+++ b/src/math.ts" },
+  { type: "hunk", text: "@@ -1,5 +1,6 @@" },
+  {
+    type: "context",
+    oldNumber: 1,
+    newNumber: 1,
+    text: "export function add(a: number, b: number) {",
+  },
+  { type: "del", oldNumber: 2, text: "  return a - b; // bug: subtracts instead of adds" },
+  { type: "add", newNumber: 2, text: "  return a + b;" },
+  { type: "add", newNumber: 3, text: "  // fixed the sign error" },
+  { type: "context", oldNumber: 3, newNumber: 4, text: "}" },
+  { type: "context", oldNumber: 4, newNumber: 5, text: "" },
+  { type: "context", oldNumber: 5, newNumber: 6, text: "export const VERSION = 2;" },
+];
+
+export const Default: Story = {
+  render: () => (
+    <div className="max-w-2xl">
+      <DiffView
+        lines={SAMPLE_LINES}
+        file="src/math.ts"
+        stats={{ additions: 2, deletions: 1 }}
+        language="typescript"
+      />
+    </div>
+  ),
+};
+
+// Dark theme — the row tints (`bg-success/10` / `bg-destructive/10`), the
+// marker/gutter tokens and the Shiki-derived syntax colour must all resolve
+// from the SCOPED dark region, not the document root (same pattern as
+// `code-block.stories.tsx`'s `DarkTheme`).
+export const DarkTheme: Story = {
+  render: () => (
+    <div className="max-w-2xl" data-theme="dark">
+      <div className="rounded-lg bg-background p-6 text-foreground">
+        <DiffView lines={SAMPLE_LINES} file="src/math.ts" stats={{ additions: 2, deletions: 1 }} />
+      </div>
+    </div>
+  ),
+};
+
+// variant="split" — two aligned columns (old-file view | new-file view).
+export const SplitVariant: Story = {
+  name: 'variant="split"',
+  render: () => (
+    <div className="max-w-3xl">
+      <DiffView lines={SAMPLE_LINES} file="src/math.ts" variant="split" />
+    </div>
+  ),
+};
+
+// pager — absorbs the upstream CodexDiff shape: scroll-position indicator, a
+// key legend, and a named `role="region"`.
+const LONG_LINES: DiffLine[] = Array.from({ length: 60 }, (_, i) => ({
+  type: i % 11 === 0 ? "del" : i % 13 === 0 ? "add" : "context",
+  oldNumber: i % 13 === 0 ? undefined : i + 1,
+  newNumber: i % 11 === 0 ? undefined : i + 1,
+  text: `line ${i + 1} of a long file`,
+})) as DiffLine[];
+
+export const Pager: Story = {
+  name: "pager",
+  render: () => (
+    <div className="max-w-2xl">
+      <DiffView lines={LONG_LINES} file="src/very-long-file.ts" pager />
+    </div>
+  ),
+};
+
+// contextLines — a long run of unchanged lines collapses behind a "show more"
+// control that restores it on click.
+const CONTEXT_RUN_LINES: DiffLine[] = [
+  { type: "hunk", text: "@@ -1,12 +1,13 @@" },
+  ...Array.from({ length: 10 }, (_, i) => ({
+    type: "context" as const,
+    oldNumber: i + 1,
+    newNumber: i + 1,
+    text: `unchanged line ${i + 1}`,
+  })),
+  { type: "add", newNumber: 11, text: "// a single new line at the end" },
+];
+
+export const CollapsedContext: Story = {
+  name: "contextLines",
+  render: () => (
+    <div className="max-w-2xl">
+      <DiffView lines={CONTEXT_RUN_LINES} contextLines={4} />
+    </div>
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const showMore = await canvas.findByRole("button", { name: /more line/ });
+    await expect(canvas.queryByText("unchanged line 5")).not.toBeInTheDocument();
+    await userEvent.click(showMore);
+    await expect(canvas.getByText("unchanged line 5")).toBeInTheDocument();
+  },
+};
+
+// LOADING — no renderable diff yet (loading-states.md). Layout-shaped
+// skeleton rows at the real row height; no layout shift once `lines` settles.
+export const Loading: Story = {
+  render: () => (
+    <div className="max-w-2xl">
+      <DiffView lines={[]} loading file="src/math.ts" />
+    </div>
+  ),
+};
+
+// STREAMING — lines are still arriving (loading-states.md `isStreaming`). What
+// exists renders as-is, including a syntactically incomplete final line, and
+// no error surface appears.
+export const Streaming: Story = {
+  name: "isStreaming",
+  render: () => (
+    <div className="max-w-2xl">
+      <DiffView
+        lines={[
+          { type: "context", oldNumber: 1, newNumber: 1, text: "export function add(a, b) {" },
+          { type: "add", newNumber: 2, text: "  return a + b" },
+        ]}
+        isStreaming
+      />
+    </div>
+  ),
+};
+
+// ─── ChangeReview composition (binding decision — architecture § 3) ────────
+//
+// DiffView (ai) and ChangeReview (ui) never import each other. The app, which
+// depends on both, wires them together through ChangeReview's existing
+// injection seams — here, the `renderHunk` render-prop seam. `ChangeHunk`
+// gains no `lines` field; `DiffLine` never moves into `ui`.
+const REVIEW_HUNK_LINES: Record<string, DiffLine[]> = {
+  "hunk-1": SAMPLE_LINES.filter((l) => l.type !== "meta"),
+};
+
+const REVIEW_HUNKS: ChangeHunk[] = [{ id: "hunk-1", title: "src/math.ts", status: "modified" }];
+
+export const ChangeReviewComposition: Story = {
+  name: "Composed into ChangeReview (ui)",
+  render: () => (
+    <div className="max-w-2xl">
+      <ChangeReview
+        hunks={REVIEW_HUNKS}
+        renderHunk={(hunk) => (
+          <DiffView lines={REVIEW_HUNK_LINES[hunk.id] ?? []} variant="inline" />
+        )}
+      />
+    </div>
+  ),
+};