# TUFFUI

> Free, open-source React components for AI-agent interfaces: chats, tool calls, approvals, plans, traces, memory and usage.

Components are React 19 + Tailwind CSS v4 + motion, distributed as a shadcn registry. Installing copies the source into components/ui and adds theme tokens (surface, surface-raised, border-strong, brand, positive, negative, warning) on top of the standard shadcn tokens.

## Surface

Shell, Panel, Inset, IconTile and ShellHeader — the borderless layers every component is framed with.

- Category: Foundations
- Docs: https://tuffui.com/components/surface
- Install: `npx shadcn@latest add https://tuffui.com/r/surface.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| Shell | `<section>` | — | Outer frame: rounded-[1.375rem] bg-surface p-1.5. |
| Panel | `<div>` | — | Content area inside a shell: rounded-2xl bg-surface-inset. |
| Inset | `<div>` | — | Deeper block inside a panel: rounded-xl bg-foreground/[0.04]. |
| IconTile | `{ icon?: Icon } & <div>` | — | Tinted 36px square holding a filled Phosphor icon, or children. |
| ShellHeader.icon | `Icon` | — | Phosphor icon shown in an IconTile, 12px from the shell edge. |
| ShellHeader.title (required) | `ReactNode` | — | Header title. |
| ShellHeader.subtitle | `ReactNode` | — | Secondary line under the title. |
| ShellHeader.aside | `ReactNode` | — | Right side — a stat, pill or actions, vertically centered. |
| ShellHeader.as | `"h2" \| "h3" \| "h4"` | `"h3"` | Heading level of the title. |

### Usage

```tsx
import { Brain } from "@phosphor-icons/react";
import { Inset, Panel, Shell, ShellHeader } from "@/components/ui/surface";

export function MemoryCard() {
  return (
    <Shell className="max-w-md">
      <ShellHeader icon={Brain} title="Memory" subtitle="5 memories" />
      <Panel className="p-4">
        <Inset className="px-3.5 py-3 font-mono text-xs">AGENTS.md</Inset>
      </Panel>
    </Shell>
  );
}
```

## Action Button

Silver primary, secondary, quiet and danger buttons in two sizes, with icons, loading and icon-only buttons.

- Category: Foundations
- Docs: https://tuffui.com/components/action-button
- Install: `npx shadcn@latest add https://tuffui.com/r/action-button.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| variant | `"primary" \| "secondary" \| "quiet" \| "danger"` | `"secondary"` | Primary is the silver gradient; use one per view. |
| size | `"sm" \| "md"` | `"sm"` | Height 32px or 36px. |
| icon | `Icon` | — | Leading Phosphor icon. |
| iconWeight | `"fill" \| "bold"` | `"fill"` | Use bold for line glyphs like check, x and arrows. |
| loading | `boolean` | `false` | Swaps the icon for a spinner and disables the button. |
| IconButton.label (required) | `string` | — | Accessible name of an icon-only button; also its native title unless `tooltip` is set. |
| IconButton.tooltip | `ReactNode \| true` | — | Shows our Tooltip instead of the native title. `true` reuses the label. Wrapping an IconButton in Tooltip also drops the title. |
| IconButton.tooltipSide / tooltipAlign | `"top" \| "bottom" / "start" \| "center" \| "end"` | `"top" / "center"` | Where the tooltip sits relative to the button. |

### Usage

```tsx
import { Check, Trash } from "@phosphor-icons/react";
import { Button, IconButton } from "@/components/ui/action-button";

<Button variant="primary" icon={Check} iconWeight="bold" onClick={approve}>
  Approve
</Button>
<Button variant="secondary" loading={saving}>Save</Button>
<IconButton icon={Trash} label="Delete" variant="danger" onClick={remove} />
```

## Choice Controls

Switch, borderless Checkbox with a mixed state, and a RadioGroup with arrow-key navigation.

- Category: Foundations
- Docs: https://tuffui.com/components/choice-controls
- Install: `npx shadcn@latest add https://tuffui.com/r/choice-controls.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| checked / defaultChecked | `boolean (Checkbox: \| "mixed")` | — | Controlled or uncontrolled state. |
| onCheckedChange | `(checked: boolean) => void` | — | Called on toggle. |
| label | `ReactNode` | — | Visible label; clicking it toggles. Without it, pass aria-label. |
| description | `ReactNode` | — | Secondary line under the label. |
| RadioGroup.value / defaultValue | `string` | — | Selected radio. |
| RadioGroup.onValueChange | `(value: string) => void` | — | Called when a radio is picked by click or arrow keys. |
| RadioGroup.label (required) | `string` | — | Accessible name of the group. |

### Usage

```tsx
import { Checkbox, Radio, RadioGroup, Switch } from "@/components/ui/choice-controls";

<Switch label="Web search" checked={web} onCheckedChange={setWeb} />
<Checkbox label="Remember this choice" checked={remember} onCheckedChange={setRemember} />
<RadioGroup label="Reasoning effort" value={effort} onValueChange={setEffort}>
  <Radio value="low" label="Low" />
  <Radio value="high" label="High" description="Thinks longer on hard tasks" />
</RadioGroup>
```

## Status Pill

Tinted status pills in five tones with icon or dot, plus a mono Tag for models, branches and transports.

- Category: Foundations
- Docs: https://tuffui.com/components/status-pill
- Install: `npx shadcn@latest add https://tuffui.com/r/status-pill.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| tone | `"neutral" \| "brand" \| "positive" \| "negative" \| "warning"` | `"neutral"` | Tinted background and text color. Always pair with text. |
| size | `"sm" \| "md"` | `"md"` | 20px or 24px tall. |
| icon | `Icon` | — | Leading Phosphor icon. |
| iconWeight | `"fill" \| "bold"` | `"fill"` | Bold for line glyphs. |

### Usage

```tsx
import { CheckCircle } from "@phosphor-icons/react";
import { StatusPill, Tag } from "@/components/ui/status-pill";

<StatusPill tone="positive" icon={CheckCircle}>Done</StatusPill>
<StatusPill tone="brand">Running</StatusPill>
<Tag>opus-5.5</Tag>
```

## Segmented Control

Radio-style segmented switch with a sliding active pill that jumps instantly from the keyboard.

- Category: Foundations
- Docs: https://tuffui.com/components/segmented-control
- Install: `npx shadcn@latest add https://tuffui.com/r/segmented-control.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| options (required) | `{ value: T; label: ReactNode; disabled?: boolean }[]` | — | Segments in order. |
| value / defaultValue | `T` | — | Selected segment; defaults to the first. |
| onValueChange | `(value: T) => void` | — | Called on click or arrow keys. |
| label (required) | `string` | — | Accessible name of the radiogroup. |
| size | `"sm" \| "md"` | `"sm"` | 32px or 36px tall. |

### Usage

```tsx
import { Segmented } from "@/components/ui/segmented-control";

<Segmented
  label="Mode"
  value={mode}
  onValueChange={setMode}
  options={[
    { value: "ask", label: "Ask" },
    { value: "plan", label: "Plan" },
    { value: "act", label: "Act" },
  ]}
/>
```

## Progress Bar

Progress and meter bars in five tones with optional stripes, plus a stacked SegmentedBar.

- Category: Foundations
- Docs: https://tuffui.com/components/progress-bar
- Install: `npx shadcn@latest add https://tuffui.com/r/progress-bar.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value (required) | `number` | — | Current value. |
| max | `number` | `100` | Upper bound. |
| tone | `"brand" \| "positive" \| "negative" \| "warning" \| "neutral"` | `"brand"` | Fill color. |
| color | `string` | — | Any CSS color for the fill. Overrides `tone`, e.g. a per-series color. |
| size | `"sm" \| "md" \| "lg"` | `"md"` | 6, 8 or 12px tall. |
| striped | `boolean` | `false` | Diagonal stripes on the fill; revealed with clip-path so they never stretch. |
| kind | `"progress" \| "meter"` | `"progress"` | progressbar for work toward done, meter for a level. |
| label (required) | `string` | — | Accessible name. |
| valueText | `string` | — | Spoken value; defaults to a percentage. |
| SegmentedBar.segments (required) | `{ id, label, value, color }[]` | — | Stacked segments in order. |

### Usage

```tsx
import { ProgressBar, SegmentedBar } from "@/components/ui/progress-bar";

<ProgressBar
  label="Requests left"
  kind="meter"
  value={limit.remaining}
  max={limit.limit}
  tone={limit.remaining < limit.limit * 0.2 ? "warning" : "brand"}
  striped
/>

<SegmentedBar
  label="Context window"
  max={200_000}
  segments={[{ id: "chat", label: "Conversation", value: 52_000, color: "var(--brand)" }]}
/>
```

## Rolling Number

Odometer-style number: each digit rolls to its new value, units and separators stay put.

- Category: Foundations
- Docs: https://tuffui.com/components/rolling-number
- Install: `npx shadcn@latest add https://tuffui.com/r/rolling-number.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value (required) | `number \| string` | — | A number, or a preformatted string like "87.2k". Only digits roll. |
| format | `(value: number) => string` | — | Formats a numeric value; defaults to en-US grouping. |
| stagger | `number` | `24` | Delay between neighbouring digits, right to left, in ms. |
| className | `string` | — | Typography is inherited; tabular figures are applied. |

### Usage

```tsx
import { RollingNumber } from "@/components/ui/rolling-number";

<RollingNumber value={formatTokens(used)} className="font-mono text-2xl" />
<RollingNumber value={cost} format={(n) => `$${n.toFixed(2)}`} />
```

## Text Field

Borderless TextField, SearchField with clear and TextArea, with label, description and error wiring.

- Category: Foundations
- Docs: https://tuffui.com/components/text-field
- Install: `npx shadcn@latest add https://tuffui.com/r/text-field.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| label | `ReactNode` | — | Visible label, linked to the control. |
| description | `ReactNode` | — | Help text, linked with aria-describedby. |
| error | `ReactNode` | — | Error text; marks the control aria-invalid and replaces the description. |
| SearchField.onClear | `() => void` | — | Shows a clear button while there is text. |
| ...rest | `<input> / <textarea> props` | — | Passed to the native control. |

### Usage

```tsx
import { SearchField, TextArea, TextField } from "@/components/ui/text-field";

<SearchField value={query} onChange={(e) => setQuery(e.target.value)} onClear={() => setQuery("")} />
<TextField label="Agent name" description="Shown in traces." error={nameError} />
<TextArea label="Instructions" rows={4} />
```

## Tooltip

Hint anchored to its trigger: scales in from the trigger side, opens instantly once one is warm.

- Category: Foundations
- Docs: https://tuffui.com/components/tooltip-hint
- Install: `npx shadcn@latest add https://tuffui.com/r/tooltip-hint.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| content (required) | `ReactNode` | — | Tooltip text. |
| children (required) | `ReactElement` | — | One focusable trigger; it gets aria-describedby while open. |
| side | `"top" \| "bottom"` | `"top"` | Which side of the trigger. |
| align | `"start" \| "center" \| "end"` | `"center"` | Alignment; the tooltip scales from that corner. |
| delay | `number` | `300` | First-hover delay in ms. Focus and warm hovers open instantly. |

### Usage

```tsx
import { Tooltip } from "@/components/ui/tooltip-hint";

<Tooltip content="Regenerate">
  <IconButton icon={ArrowClockwise} label="Regenerate" />
</Tooltip>
```

## Action Menu

Dropdown and right-click menus — items with icons and shortcuts, submenus, checkable items and a destructive group.

- Category: Foundations
- Docs: https://tuffui.com/components/action-menu
- Install: `npx shadcn@latest add https://tuffui.com/r/action-menu.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| groups (required) | `MenuGroup[]` | — | Item groups, separated by spacing and an optional small label. |
| trigger (required) | `ReactElement` | — | Menu only. A button-like element that opens it. |
| children (required) | `ReactElement` | — | ContextMenu only. The area that opens it on right-click, long-press or the context-menu key. |
| side / align | `"top" \| "right" \| "bottom" \| "left" / "start" \| "center" \| "end"` | `"bottom" / "start"` | Menu only. Placement against the trigger; flips when there's no room. |
| open / onOpenChange | `boolean / (open: boolean) => void` | — | Optional control of the open state. |

### Usage

```tsx
import { Menu, ContextMenu, type MenuGroup } from "@/components/ui/action-menu";

const groups: MenuGroup[] = [
  {
    items: [
      { id: "copy", label: "Copy", icon: Copy, shortcut: "⌘C", onSelect: copy },
      { id: "regen", type: "submenu", label: "Regenerate with", items: [
        { id: "model", type: "radio", value: model, onValueChange: setModel,
          options: [{ value: "opus", label: "opus-5.5" }, { value: "sonnet", label: "sonnet-5.5" }] },
      ] },
    ],
  },
  { label: "View", items: [
    { id: "reasoning", type: "checkbox", label: "Show reasoning", checked, onCheckedChange: setChecked },
  ] },
  { items: [{ id: "delete", label: "Delete", icon: Trash, destructive: true, onSelect: remove }] },
];

<Menu groups={groups} trigger={<IconButton icon={DotsThree} label="Actions" />} />

<ContextMenu groups={groups}>
  <div tabIndex={0}>Right-click me</div>
</ContextMenu>
```

### Types

```ts
type MenuGroup = { id?: string; label?: string; items: MenuItem[] };

type MenuItem =
  | { type?: "item"; id: string; label: ReactNode; icon?: Icon; shortcut?: string;
      description?: ReactNode; destructive?: boolean; disabled?: boolean; onSelect?: () => void }
  | { type: "checkbox"; id: string; label: ReactNode; icon?: Icon;
      checked: boolean; onCheckedChange: (checked: boolean) => void }
  | { type: "radio"; id: string; value: string; onValueChange: (value: string) => void;
      options: { value: string; label: ReactNode; icon?: Icon; disabled?: boolean }[] }
  | { type: "submenu"; id: string; label: ReactNode; icon?: Icon; items: MenuItem[] };
```

## Popover Panel

A panel anchored to its trigger — grows from it, closes on outside click or Esc, keeps focus inside.

- Category: Foundations
- Docs: https://tuffui.com/components/popover-panel
- Install: `npx shadcn@latest add https://tuffui.com/r/popover-panel.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| trigger (required) | `ReactElement` | — | A button-like element that toggles the panel. |
| children (required) | `ReactNode` | — | Panel content. |
| title | `ReactNode` | — | Heading at the top; a string title also names the panel for screen readers. |
| showClose | `boolean` | `false` | Adds a close button to the header. |
| side / align | `"top" \| "right" \| "bottom" \| "left" / "start" \| "center" \| "end"` | `"bottom" / "center"` | Placement; the panel grows from the trigger's side and flips when there's no room. |
| open / onOpenChange | `boolean / (open: boolean) => void` | — | Optional control of the open state. |
| className | `string` | — | Classes for the panel, e.g. a different width. |

### Usage

```tsx
import { Popover, PopoverClose } from "@/components/ui/popover-panel";

<Popover title="Rename chat" showClose trigger={<Button>Rename</Button>}>
  <form onSubmit={save}>
    <TextField name="title" label="Title" defaultValue={title} />
    <PopoverClose asChild>
      <Button type="submit" variant="primary">Save</Button>
    </PopoverClose>
  </form>
</Popover>
```

## Modal Sheet

Centered dialog and edge sheet (drawer) — focus trap, scroll lock, Esc and backdrop to close.

- Category: Foundations
- Docs: https://tuffui.com/components/modal-sheet
- Install: `npx shadcn@latest add https://tuffui.com/r/modal-sheet.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| title (required) | `ReactNode` | — | Heading; also the accessible name. |
| description | `ReactNode` | — | Secondary line under the title. |
| children | `ReactNode` | — | Body, placed in an inset panel. |
| footer | `ReactNode` | — | Actions row, right-aligned. |
| trigger | `ReactElement` | — | Optional element that opens it; otherwise control open yourself. |
| open / onOpenChange | `boolean / (open: boolean) => void` | — | Optional control of the open state. |
| size | `"sm" \| "md" \| "lg"` | `"md"` | Dialog only. Max width. |
| side | `"left" \| "right" \| "bottom"` | `"left"` | Sheet only. The edge it slides in from. |

### Usage

```tsx
import { Dialog, DialogClose, Sheet } from "@/components/ui/modal-sheet";

<Dialog
  title="Share chat"
  description="Anyone with the link can read it."
  trigger={<Button>Share</Button>}
  footer={
    <>
      <DialogClose asChild><Button variant="quiet">Cancel</Button></DialogClose>
      <Button variant="primary" onClick={copyLink}>Copy link</Button>
    </>
  }
>
  <TextField label="Link" readOnly value={url} />
</Dialog>

<Sheet side="left" title="Chats" open={open} onOpenChange={setOpen}>
  <ConversationList data={chats} />
</Sheet>
```

## Toast Stack

Notifications that stack, expand on hover, pause while hovered, swipe or click to dismiss, with actions.

- Category: Foundations
- Docs: https://tuffui.com/components/toast-stack
- Install: `npx shadcn@latest add https://tuffui.com/r/toast-stack.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| visible | `number` | `3` | Toaster. Toasts shown in the collapsed stack; hover fans them all out. |
| position | `"bottom-right" \| "bottom-center"` | `"bottom-right"` | Toaster. Where the stack sits. |
| toast(title, options?) | `(title: ReactNode, options?: ToastOptions) => string` | — | Shows a toast and returns its id. Also .success, .error, .loading, .promise and .dismiss(id). |

### Usage

```tsx
import { Toaster, toast } from "@/components/ui/toast-stack";

// Once, near the root of the app:
<Toaster />

// Anywhere:
toast.success("Link copied");
toast.error("Couldn't send", { description: "Check your connection." });
toast("Chat archived", { action: { label: "Undo", onClick: restore } });
toast.promise(exportChat(), {
  loading: "Exporting…",
  success: "Exported to Markdown",
  error: "Export failed",
});
```

### Types

```ts
type ToastOptions = {
  id?: string;           // reuse an id to update a toast in place
  description?: ReactNode;
  action?: { label: string; onClick: () => void };
  duration?: number;     // ms; default 4000, errors 6000, loading until updated
};
```

## Select Field

Select and searchable combobox — options with icons and hints, groups, keyboard typeahead.

- Category: Foundations
- Docs: https://tuffui.com/components/select-field
- Install: `npx shadcn@latest add https://tuffui.com/r/select-field.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| options (required) | `SelectOption[] \| SelectGroup[]` | — | Flat options or labelled groups (Combobox takes a flat list). |
| value / defaultValue / onValueChange | `string` | — | Selected value. Combobox passes null when cleared. |
| label / description / error | `ReactNode` | — | Field label, help text and error, wired like TextField. |
| placeholder | `string` | — | Shown with no value. |
| onQueryChange | `(query: string) => void` | — | Combobox. Called as the user types; when set, options are shown as given. |
| loading / emptyText | `boolean / string` | — | Combobox. Spinner while searching and the no-results line. |
| name / required / disabled | `string / boolean / boolean` | — | Select. Form integration. |

### Usage

```tsx
import { Select, Combobox } from "@/components/ui/select-field";

<Select
  label="Model"
  value={model}
  onValueChange={setModel}
  options={[
    { label: "Anthropic", options: [
      { value: "opus", label: "opus-5.5", icon: Brain, description: "Deep reasoning" },
      { value: "sonnet", label: "sonnet-5.5", icon: Cpu },
    ] },
  ]}
/>

<Combobox
  label="Tool"
  options={results}
  loading={searching}
  onQueryChange={search}   // filter on the server; omit to filter by label
  onValueChange={setTool}
/>
```

### Types

```ts
type SelectOption = { value: string; label: string; icon?: Icon; description?: string; disabled?: boolean };
type SelectGroup = { label?: string; options: SelectOption[] };
```

## Tab Panels

Tabs with panels — sliding indicator, keyboard navigation, lazy panels and counts.

- Category: Foundations
- Docs: https://tuffui.com/components/tab-panels
- Install: `npx shadcn@latest add https://tuffui.com/r/tab-panels.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| Tabs.value / defaultValue (required) | `string` | — | Selected tab. `defaultValue` is required for the uncontrolled case. |
| Tabs.onValueChange | `(value: string) => void` | — | Called on click or, with automatic activation, on arrow keys. |
| Tabs.variant | `"default" \| "pills"` | `"default"` | A short bar under the active tab, or a raised pill behind it. |
| Tabs.activation | `"automatic" \| "manual"` | `"automatic"` | Automatic selects as focus moves; manual moves focus only, Enter or Space selects. |
| TabList.label (required) | `string` | — | Accessible name of the tab list. |
| Tab.count | `number` | — | Small count after the label. |
| TabPanel.lazy | `boolean` | `false` | Mount the panel the first time it's selected; it stays mounted after. |

### Usage

```tsx
import { Tab, TabList, TabPanel, Tabs } from "@/components/ui/tab-panels";

<Tabs defaultValue="answer" variant="pills">
  <TabList label="Response">
    <Tab value="answer">Answer</Tab>
    <Tab value="sources" count={sources.length}>Sources</Tab>
  </TabList>
  <TabPanel value="answer">{answer}</TabPanel>
  <TabPanel value="sources" lazy>
    <SourceList data={{ sources }} />
  </TabPanel>
</Tabs>
```

## Disclosure

Accordion and single collapsible sections with smooth height animation.

- Category: Foundations
- Docs: https://tuffui.com/components/disclosure
- Install: `npx shadcn@latest add https://tuffui.com/r/disclosure.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| Accordion.items (required) | `AccordionItem[]` | — | Sections in order: id, title, optional icon and meta, content. |
| Accordion.type | `"single" \| "multiple"` | `"single"` | Single keeps at most one section open. |
| Accordion.value / defaultValue / onValueChange | `string[]` | — | Ids of open sections, controlled or not. |
| Collapsible.open / defaultOpen / onOpenChange | `boolean` | — | Open state of the single section. |
| title / icon / meta | `ReactNode / Icon / ReactNode` | — | Header row: title, a filled Phosphor icon and right-aligned meta. |

### Usage

```tsx
import { Accordion, Collapsible } from "@/components/ui/disclosure";

<Accordion
  type="multiple"
  items={steps.map((s) => ({ id: s.id, title: s.title, meta: s.duration, content: s.output }))}
/>

<Collapsible title="Thought for 6s" defaultOpen={false}>
  {reasoning}
</Collapsible>
```

### Types

```ts
type AccordionItem = {
  id: string;
  title: ReactNode;
  icon?: Icon; // Phosphor
  meta?: ReactNode;
  content: ReactNode;
  disabled?: boolean;
};
```

## Agent Avatar

Avatars for agents and people — initials or image, presence and activity state, stacked groups.

- Category: Foundations
- Docs: https://tuffui.com/components/agent-avatar
- Install: `npx shadcn@latest add https://tuffui.com/r/agent-avatar.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| name (required) | `string` | — | Used for initials, tint and the accessible name. |
| src | `string` | — | Image URL; without it, initials on a tint derived from the name. |
| size | `"xs" \| "sm" \| "md" \| "lg"` | `"md"` | 20, 28, 36 or 48px. |
| kind | `"agent" \| "person"` | `"person"` | Agents are rounded squares, people circles. |
| status | `"online" \| "away" \| "busy" \| "working"` | — | Badge in the corner; working spins. Always included in the accessible name. |
| AvatarGroup.people / max | `AvatarProps[] / number` | — | Overlapping avatars with names in tooltips; the rest collapse into +N. |

### Usage

```tsx
import { Avatar, AvatarGroup } from "@/components/ui/agent-avatar";

<Avatar name="i18n-agent" kind="agent" status={run.active ? "working" : "online"} />

{/* Match --avatar-gap to the surface the group sits on. */}
<div className="[--avatar-gap:var(--surface-inset)]">
  <AvatarGroup people={participants} max={4} />
</div>
```

### Types

```ts
/* CSS variable: --avatar-gap — the colour of the gap around badges and
   overlapping avatars. Defaults to var(--background). */
```

## Loading Skeleton

Placeholders for answers, lists and cards while they load.

- Category: Foundations
- Docs: https://tuffui.com/components/loading-skeleton
- Install: `npx shadcn@latest add https://tuffui.com/r/loading-skeleton.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| Skeleton | `div props` | — | One block; size it with className. Hidden from assistive tech. |
| SkeletonGroup.label | `string` | `"Loading"` | Wraps skeletons in a status region announced once. |
| MessageSkeleton.lines | `number` | `3` | Text lines under the name. |
| CardSkeleton.media | `boolean` | `true` | Show the image area. |

### Usage

```tsx
import { MessageSkeleton, Skeleton, SkeletonGroup } from "@/components/ui/loading-skeleton";

{loading ? <MessageSkeleton /> : <StreamingMessage data={message} />}

<SkeletonGroup label="Loading history" className="flex flex-col gap-2">
  {Array.from({ length: 6 }, (_, i) => <Skeleton key={i} className="h-8" />)}
</SkeletonGroup>
```

## Range Slider

Single and range sliders with steps, marks and value labels — for temperature, length, budgets.

- Category: Foundations
- Docs: https://tuffui.com/components/range-slider
- Install: `npx shadcn@latest add https://tuffui.com/r/range-slider.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| defaultValue (required) | `number \| [number, number]` | — | Initial value. A pair renders a range with two thumbs. |
| value | `number \| [number, number]` | — | Controlled value. |
| onValueChange | `(value) => void` | — | Fires while dragging. |
| onValueCommit | `(value) => void` | — | Fires when a drag or key press ends. |
| min / max / step | `number` | `0 / 100 / 1` | Range and snapping. |
| marks | `{ value; label? }[]` | — | Labels under the track. |
| striped | `boolean` | `false` | Stripes on the fill. |
| label (required) | `string` | — | Accessible name, shown above. |
| format | `(value: number) => string` | — | Text for the bubble, the header and aria-valuetext. |
| disabled | `boolean` | `false` | Dims and locks it. |

### Usage

```tsx
import { Slider } from "@/components/ui/range-slider";

<Slider
  label="Temperature"
  value={temperature}
  defaultValue={0.7}
  onValueChange={setTemperature}
  min={0}
  max={2}
  step={0.1}
  format={(v) => v.toFixed(1)}
/>

// Two thumbs: pass a [low, high] pair.
<Slider label="Response length" defaultValue={[150, 600]} max={1000} step={50} striped />
```

## Key Hint

Keyboard shortcut hints that adapt to the platform — Cmd on Mac, Ctrl elsewhere.

- Category: Foundations
- Docs: https://tuffui.com/components/key-hint
- Install: `npx shadcn@latest add https://tuffui.com/r/key-hint.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| keys (required) | `string` | — | KeyCombo: keys joined by "+". mod, shift, alt, ctrl, enter, esc, arrows and letters are mapped per platform. |
| size | `"sm" \| "md"` | `"sm"` | Chip size for Kbd and KeyCombo. |
| children | `ReactNode` | — | Kbd: the key label. |

### Usage

```tsx
import { Kbd, KeyCombo } from "@/components/ui/key-hint";

<KeyCombo keys="mod+k" />      // ⌘ K on Mac, Ctrl K elsewhere
<KeyCombo keys="shift+enter" />
<Kbd>Esc</Kbd>
```

### Types

```ts
function formatKeys(combo: string, onMac: boolean): string[];
function useIsMac(): boolean; // false during prerender, real value after mount
```

## Loader

Spinner and thinking indicators in a few sizes, with an accessible label.

- Category: Foundations
- Docs: https://tuffui.com/components/loader
- Install: `npx shadcn@latest add https://tuffui.com/r/loader.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| size | `"sm" \| "md" \| "lg"` | `"md"` | Spinner and Thinking size. |
| label | `string` | `"Loading"` | Spinner: spoken label, also the visible text with showLabel. |
| showLabel | `boolean` | `false` | Spinner: show the label next to the ring. |
| words | `string[]` | `[]` | Thinking: verbs to cycle through next to the dots. Each swaps in from below. |
| interval | `number` | `1800` | Thinking: ms per word. |

### Usage

```tsx
import { Spinner, Thinking } from "@/components/ui/loader";

<Spinner label="Loading history" showLabel />
<Thinking words={["Thinking", "Searching", "Writing"]} />
```

## Empty State

Empty, no-results and error states with an icon, message and actions.

- Category: Foundations
- Docs: https://tuffui.com/components/empty-state
- Install: `npx shadcn@latest add https://tuffui.com/r/empty-state.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| title (required) | `ReactNode` | — | One line saying what's empty or what failed. |
| description | `ReactNode` | — | What to do next. |
| icon | `Icon` | — | Phosphor icon, filled. Errors default to a warning. |
| action / secondaryAction | `{ label, onClick, icon?, iconWeight? }` | — | Silver primary and a quiet secondary button. |
| tone | `"neutral" \| "error"` | `"neutral"` | Error tints the icon and announces as an alert. |
| onRetry | `() => void` | — | With tone error and no action, adds a Retry button. |
| compact | `boolean` | `false` | Row layout for empty lists inside a panel. |

### Usage

```tsx
import { EmptyState } from "@/components/ui/empty-state";

{chats.length === 0 && (
  <EmptyState
    icon={ChatsCircle}
    title="No conversations yet"
    description="Start a chat and it will show up here."
    action={{ label: "New chat", onClick: newChat, icon: Plus, iconWeight: "bold" }}
  />
)}

{error && <EmptyState tone="error" title="Couldn't load history" onRetry={reload} />}
```

## Date Field

Calendar and date picker — month grid, ranges, keyboard navigation and min / max.

- Category: Foundations
- Docs: https://tuffui.com/components/date-field
- Install: `npx shadcn@latest add https://tuffui.com/r/date-field.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| mode | `"single" \| "range"` | `"single"` | Calendar: one day, or a from / to range picked with two clicks. |
| value | `Date \| null \| { from; to }` | — | Selected day, or range in range mode. Calendar is controlled. |
| onValueChange | `(value) => void` | — | Fires on pick. DatePicker closes its popover after. |
| min / max | `Date` | — | Days outside are disabled. |
| isDisabled | `(date: Date) => boolean` | — | Disable individual days, e.g. weekends. |
| locale | `string` | — | Month and weekday names via Intl. |
| label / placeholder / formatOptions | `string / string / Intl.DateTimeFormatOptions` | — | DatePicker trigger text. |

### Usage

```tsx
import { Calendar, DatePicker } from "@/components/ui/date-field";

<DatePicker
  label="Ship the release on"
  value={date}
  onValueChange={setDate}
  min={new Date()}
  isDisabled={(d) => d.getDay() === 0 || d.getDay() === 6}
/>

<Calendar mode="range" value={range} onValueChange={setRange} />
```

### Types

```ts
type DateRange = { from: Date | null; to: Date | null };
// Keys: arrows move a day / week, Home / End the week, PageUp / PageDown the month,
// Enter or Space picks. Without a value the calendar opens on the current month,
// so pass a value when you prerender to keep server and client markup equal.
```

## Drop Zone

Drag-and-drop file target for a chat — accepts types and size limits, shows why a file was rejected.

- Category: Foundations
- Docs: https://tuffui.com/components/drop-zone
- Install: `npx shadcn@latest add https://tuffui.com/r/drop-zone.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| onFiles (required) | `(accepted: File[]) => void` | — | Files that passed the rules. |
| onReject | `(rejected: { file; reason }[]) => void` | — | Files turned away, with a readable reason. DropZone also lists them. |
| accept | `string` | — | MIME types or extensions, like "image/*,.pdf". |
| maxSize | `number` | — | Bytes per file. |
| multiple | `boolean` | `true` | Allow several files. |
| maxFiles | `number` | — | Most files per drop. |
| title / hint | `string` | — | DropZone text; the hint defaults to the rules. |
| show | `boolean` | — | DropOverlay: force the overlay, e.g. for a page-level drag you track. |

### Usage

```tsx
import { DropOverlay, DropZone } from "@/components/ui/drop-zone";

<DropZone
  accept="application/pdf,image/*,.csv"
  maxSize={10 * 1024 * 1024}
  onFiles={(files) => upload(files)}
/>

// Over a whole chat: shows an overlay while files are dragged in.
<DropOverlay accept="image/*,.pdf" onFiles={attach}>
  <ChatThread data={thread} />
</DropOverlay>
```

### Types

```ts
function checkFiles(files: File[], rules: FileRules): {
  accepted: File[];
  rejected: { file: File; reason: string }[];
};
```

## AI Chat

A complete chat app screen — history sidebar, a thread with tool calls, cited answers and feedback, follow-up chips and a composer with a context meter.

- Category: Screens
- Docs: https://tuffui.com/components/ai-chat
- Install: `npx shadcn@latest add https://tuffui.com/r/ai-chat.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| data (required) | `AIChatData` | — | History, the open chat (title, model, turns), starter cards, follow-up chips, context usage and the signed-in user. |
| status | `"idle" \| "streaming"` | `"idle"` | While streaming, the composer queues new messages and follow-up chips are hidden. |
| onSend | `(text: string) => void` | — | A message from the composer, a starter card or a follow-up chip. |
| onStop | `() => void` | — | Stop the current run. |
| onNewChat | `() => void` | — | From the history panel. Pass empty `messages` to show the starter cards. |
| onSelectConversation | `(conversation: Conversation) => void` | — | A chat picked in the history sidebar or drawer. |
| onShare | `() => void` | — | Share button in the header. |
| sidebarOpen | `boolean` | — | Controls the history sidebar at wide widths. The header button and mod+\ toggle it; below 56rem the history opens as a drawer instead. |
| defaultSidebarOpen | `boolean` | `true` | Initial sidebar state when uncontrolled. |
| onSidebarOpenChange | `(open: boolean) => void` | — | Called when the sidebar is shown or hidden. |
| className | `string` | — | Extra classes for the root. |

### Usage

```tsx
import { AIChat } from "@/components/ai-chat";
import { ToolCallBlock } from "@/components/ui/tool-call-block";
import { SourceList } from "@/components/ui/source-list";
import { StreamingMessage } from "@/components/ui/streaming-message";

export function ChatScreen({ chat, run }: { chat: Chat; run: AgentRun }) {
  return (
    <AIChat
      data={{
        conversations: chat.history,
        activeId: chat.id,
        title: chat.title,
        model: run.model,
        user: { name: chat.user.name },
        starters: chat.starters,
        followUps: run.done ? run.followUps : undefined,
        context: { limit: run.contextLimit, segments: run.contextSegments },
        // Each turn's content is any React node — compose answers from components.
        messages: chat.turns.map((turn) => ({
          id: turn.id,
          role: turn.role,
          at: turn.createdAt,
          content:
            turn.role === "user" ? (
              turn.text
            ) : (
              <>
                {turn.toolCalls.map((call) => (
                  <ToolCallBlock key={call.id} data={call} />
                ))}
                {turn.streaming ? (
                  <StreamingMessage
                    data={{ content: turn.text, status: "streaming" }}
                    showHeader={false}
                  />
                ) : (
                  <SourceList data={{ sources: turn.sources, text: turn.text }} />
                )}
              </>
            ),
        })),
      }}
      status={run.streaming ? "streaming" : "idle"}
      onSend={(text) => run.send(text)}
      onStop={() => run.stop()}
      onNewChat={() => chat.create()}
      onSelectConversation={(c) => chat.open(c.id)}
      onShare={() => chat.share()}
    />
  );
}
```

### Types

```ts
type AIChatData = {
  conversations: Conversation[];        // from conversation-list
  activeId?: string;
  title: string;
  model: string;
  messages: ThreadMessage[];            // from chat-thread; content is a ReactNode
  followUps?: PromptSuggestion[];       // chips under the last answer
  starters: PromptSuggestion[];         // cards for an empty chat
  context: { limit: number; segments: ContextSegment[] };
  user: { name: string; avatar?: string };
};

// The screen fills its parent and lays out by its own width (container queries):
// a history sidebar from 56rem, a drawer below that. Give the parent a height.
```

## Coding Agent

An agent working in a repo — chat with plan and permission requests on one side, file changes, terminal and a live preview on the other.

- Category: Screens
- Docs: https://tuffui.com/components/coding-agent
- Install: `npx shadcn@latest add https://tuffui.com/r/coding-agent.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| data (required) | `CodingAgentData` | — | The task, repo and branch, the thread, the live activity line, changed files, the last terminal run, checkpoints and the preview. |
| status | `"idle" \| "streaming"` | `"idle"` | While streaming, the composer queues follow-ups and shows Stop instead of Send. |
| tab | `"changes" \| "terminal" \| "preview"` | — | Controls the work panel tab. Uncontrolled it starts on Changes. |
| onTabChange | `(tab: WorkTab) => void` | — | Called when the user picks a tab. |
| onSend | `(message: ComposerMessage) => void` | — | Called with the text, mode (ask, plan or act), context and model. |
| onStop | `() => void` | — | Stop from the composer or the activity line. |
| onApply | `(selection: HunkSelection) => void` | — | Apply the kept hunks from the Changes tab. |
| onDiscard | `() => void` | — | Discard every change. |
| applying | `boolean` | `false` | Puts the Apply button in its loading state. |
| onRestore | `(checkpoint: Checkpoint) => void` | — | Called after the user confirms restoring to a checkpoint. |
| className | `string` | — | Extra classes for the root. |

### Usage

```tsx
import { CodingAgent } from "@/components/coding-agent";
import { ToolCallBlock } from "@/components/ui/tool-call-block";
import { ToolApprovalQueue } from "@/components/ui/tool-approval-queue";

export function AgentScreen({ run }: { run: AgentRun }) {
  return (
    <div className="h-dvh">
      <CodingAgent
        data={{
          title: run.task.title,
          repo: run.repo,
          branch: run.branch,
          model: run.model,
          user: { name: run.user.name },
          // Each turn's content is any React node — tool calls, approvals.
          messages: run.turns.map((turn) => ({
            id: turn.id,
            role: turn.role,
            at: turn.createdAt,
            content:
              turn.role === "user" ? (
                turn.text
              ) : (
                <>
                  {turn.calls.map((call) => (
                    <ToolCallBlock key={call.id} data={call} />
                  ))}
                  {turn.approvals.length > 0 && (
                    <ToolApprovalQueue
                      data={turn.approvals}
                      layout="flat"
                      onDecide={(requests, decision, scope) =>
                        run.decide(requests, decision, scope)
                      }
                    />
                  )}
                </>
              ),
          })),
          activity: run.working ? run.status : undefined,
          files: run.changes,
          terminal: run.lastCommand,
          checkpoints: run.checkpoints,
          preview: { url: run.previewUrl, content: <iframe src={run.previewUrl} /> },
        }}
        status={run.working ? "streaming" : "idle"}
        onSend={(message) => run.send(message.text, message.mode)}
        onStop={() => run.stop()}
        onApply={(selection) => run.apply(selection)}
        onDiscard={() => run.discard()}
        onRestore={(checkpoint) => run.restore(checkpoint.id)}
      />
    </div>
  );
}
```

### Types

```ts
type CodingAgentData = {
  title: string;
  repo: string;
  branch: string;
  model: string;
  user: { name: string; avatar?: string };
  messages: ThreadMessage[];            // from chat-thread; content is a ReactNode
  activity?: AgentStatusData;           // live status at the end of the thread
  files: FileChange[];                  // from file-changes
  terminal: TerminalRun;                // from terminal-output
  checkpoints: Checkpoint[];            // from checkpoint-timeline
  preview: { url: string; content: ReactNode };
};

// Lays out by its own width: from 960px chat and the work panel sit side by side
// and either can be collapsed; below that a switch shows Chat, Changes, Terminal
// or Preview. Give the parent a height.
```

## Data Answer

An analytics question answered with KPI cards, a chart and a table, plus follow-up questions to dig further.

- Category: Screens
- Docs: https://tuffui.com/components/data-answer
- Install: `npx shadcn@latest add https://tuffui.com/r/data-answer.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| data (required) | `DataAnswerData` | — | Title, model, data sources and saved questions for the sidebar, the thread's messages, follow-up chips and the user. |
| status | `"idle" \| "streaming"` | `"idle"` | While streaming the composer queues messages and follow-ups are hidden. |
| onSend | `(text: string) => void` | — | A message from the composer, a follow-up chip or a saved question. |
| onStop | `() => void` | — | Stop the running answer. |
| sidebarOpen | `boolean` | — | Controls the sidebar on wide screens (from 56rem). Below that the toggle opens it as a drawer. |
| onSidebarOpenChange | `(open: boolean) => void` | — | Called when the sidebar toggle is used on a wide screen. |
| className | `string` | — | Extra classes for the root. |

### Usage

```tsx
import { DataAnswer } from "@/components/data-answer";
import { ChartCard } from "@/components/ui/chart-card";
import { DataTable } from "@/components/ui/data-table";
import { StatGrid } from "@/components/ui/stat-grid";
import { ToolCallBlock } from "@/components/ui/tool-call-block";

export function AnalyticsScreen({ workspace, chat }: { workspace: Workspace; chat: Chat }) {
  return (
    <DataAnswer
      data={{
        title: chat.title,
        model: chat.model,
        user: { name: workspace.user.name },
        sources: workspace.sources, // { id, name, detail, status: "synced" | "syncing" | "stale" }
        saved: workspace.savedQuestions,
        followUps: chat.done ? chat.followUps : undefined,
        // An answer is any React node — compose it from the data components.
        messages: chat.turns.map((turn) => ({
          id: turn.id,
          role: turn.role,
          at: turn.createdAt,
          content:
            turn.role === "user" ? (
              turn.text
            ) : (
              <div className="flex flex-col gap-3">
                <ToolCallBlock data={turn.query} />
                <p>{turn.text}</p>
                {turn.stats && <StatGrid data={turn.stats} sparklines />}
                {turn.chart && <ChartCard {...turn.chart} />}
                {turn.table && <DataTable {...turn.table} />}
              </div>
            ),
        })),
      }}
      status={chat.streaming ? "streaming" : "idle"}
      onSend={(text) => chat.ask(text)}
      onStop={() => chat.stop()}
    />
  );
}
```

### Types

```ts
type DataAnswerData = {
  title: string;
  model: string;
  sources: { id: string; name: string; detail?: string; status: "synced" | "syncing" | "stale" }[];
  saved: { id: string; title: string; prompt?: string }[];
  messages: ThreadMessage[]; // content: any ReactNode
  followUps?: PromptSuggestion[];
  user: { name: string; avatar?: string };
};
```

## Booking Assistant

An assistant that acts — compares options, picks a time, fills a form and confirms before it books.

- Category: Screens
- Docs: https://tuffui.com/components/booking-assistant
- Install: `npx shadcn@latest add https://tuffui.com/r/booking-assistant.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| data (required) | `BookingAssistantData` | — | Title, model, user, thread messages (any React content) and the summary panel rows. A row with no value shows as not decided yet. |
| status | `"idle" \| "streaming"` | `"idle"` | While streaming, the composer queues messages and shows Stop. |
| onSend | `(text: string) => void` | — | Called with the composer text. |
| onStop | `() => void` | — | Stops the running answer. |
| summaryOpen | `boolean` | — | Controls the side panel (from 64rem wide). Uncontrolled and open by default; below 64rem the same button opens a drawer. |
| onSummaryOpenChange | `(open: boolean) => void` | — | Called when the side panel is shown or hidden. |
| className | `string` | — | Extra classes for the root. |

### Usage

```tsx
import { BookingAssistant } from "@/components/booking-assistant";
import { AgentQuestion } from "@/components/ui/agent-question";
import { ConfirmationCard } from "@/components/ui/confirmation-card";
import { SlotPicker } from "@/components/ui/slot-picker";

export function TripPlanner({ trip, run }: { trip: Trip; run: AgentRun }) {
  return (
    <BookingAssistant
      status={run.streaming ? "streaming" : "idle"}
      onSend={(text) => run.send(text)}
      onStop={() => run.stop()}
      data={{
        title: trip.name,
        model: run.model,
        user: { name: trip.owner.name },
        // Each answer can be an interactive component the agent asked for.
        messages: run.turns.map((turn) => ({
          id: turn.id,
          role: turn.role,
          at: turn.createdAt,
          content: renderTurn(turn), // AgentQuestion, SlotPicker, FormCard, ConfirmationCard…
        })),
        summary: {
          title: "Trip summary",
          estimate: trip.estimate,
          items: [
            { id: "venue", label: "Venue", value: trip.venue?.name },
            { id: "call", label: "Kickoff call", value: trip.call?.label },
            { id: "booking", label: "Booking", value: trip.bookingRef },
          ],
        },
      }}
    />
  );
}
```

### Types

```ts
type BookingAssistantData = {
  title: string;
  model: string;
  messages: ThreadMessage[]; // { id, role, at, content: ReactNode }
  summary: { title: string; items: SummaryItem[]; estimate?: string };
  user: { name: string; avatar?: string };
};

type SummaryItem = {
  id: string;
  label: string;
  value?: string; // empty until decided
  icon?: Icon;
};
```

## Agent Console

A team view of agents in production — background runs, a trace, eval results, usage and rate limits.

- Category: Screens
- Docs: https://tuffui.com/components/agent-console
- Install: `npx shadcn@latest add https://tuffui.com/r/agent-console.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| data (required) | `AgentConsoleData` | — | Everything the console shows: nav team, KPIs, background runs, the selected run's spans, eval results, usage, rate limits, context and an optional incident. |
| section | `"agents" \| "runs" \| "evals" \| "usage" \| "settings"` | — | Active nav item. Uncontrolled by default. |
| onSectionChange | `(section: ConsoleSection) => void` | — | Called when a nav item is picked. |
| onSelectAgent | `(agent: BackgroundAgent) => void` | — | Open a background run, e.g. to load its trace. |
| onDecide | `(requests, decision, scope) => void` | — | Forwarded to the incident's ToolApprovalQueue. |
| onRetryLimits | `() => void` | — | Forwarded to RateLimits' Retry now. |
| onAcknowledge | `() => void` | — | The incident banner's Acknowledge button. |
| className | `string` | — | Extra classes for the root. The screen fills its parent. |

### Usage

```tsx
import { AgentConsole } from "@/components/agent-console";

export function ConsoleScreen({ fleet }: { fleet: Fleet }) {
  return (
    <AgentConsole
      data={{
        title: "Agents",
        environment: fleet.env,
        team: fleet.agents.map((a) => ({ id: a.id, name: a.name, status: a.presence })),
        stats: fleet.kpis, // StatGrid items
        agents: fleet.runs, // BackgroundAgents items
        run: { name: fleet.selected.name, spans: fleet.selected.spans, elapsedMs: fleet.selected.ms },
        evals: fleet.latestEval, // EvalResults data
        usage: fleet.usage, // UsageSummary data
        limits: fleet.rateLimits, // RateLimits data
        context: fleet.context, // ContextWindowMeter data
        incident: fleet.incident && {
          title: fleet.incident.title,
          description: fleet.incident.summary,
          approvals: fleet.incident.pendingActions, // ToolApprovalQueue items
        },
      }}
      onSelectAgent={(agent) => openRun(agent.id)}
      onDecide={(requests, decision, scope) => resolve(requests, decision, scope)}
      onAcknowledge={() => acknowledge(fleet.incident.id)}
    />
  );
}

// Mount nothing else for toasts: the screen renders its own Toaster, so
// toast("…") calls from anywhere show up inside the console.
```

### Types

```ts
type AgentConsoleData = {
  title: string;
  environment?: string;
  team: { id: string; name: string; status?: "online" | "away" | "busy" | "working" }[];
  stats: Stat[];                 // from stat-grid
  agents: BackgroundAgent[];     // from background-agents
  run: { name: string; spans: TraceSpan[]; elapsedMs: number; failed?: boolean };
  evals: EvalResultsProps["data"];
  usage: UsageSummaryProps["data"];
  limits: RateLimitsProps["data"];
  context: { limit: number; segments: ContextSegment[]; model?: string };
  incident?: { title: string; description: string; approvals: ToolApprovalRequest[] };
};
```

## Support Widget

A support bot embedded on a website — launcher bubble, quick replies, order lookup, handoff to a human and a rating at the end.

- Category: Screens
- Docs: https://tuffui.com/components/support-widget
- Install: `npx shadcn@latest add https://tuffui.com/r/support-widget.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| data (required) | `SupportWidgetData` | — | Bot, the person who takes over, the visitor, the turns, quick replies and the current mode. |
| children | `ReactNode` | — | The host page the widget floats over. It stays usable while the panel is open. |
| open / defaultOpen / onOpenChange | `boolean / boolean / (open: boolean) => void` | `— / false / —` | Whether the panel is open. The launcher toggles it, Esc and the minimise button close it. |
| onSend | `(text: string) => void` | — | A message from the composer or a quick reply. |
| onRate | `(feedback) => void` | — | The 1–5 rating, reasons and note from the end-of-chat rating. |
| onClose | `() => void` | — | The end-chat button. Minimising only hides the panel. |
| className | `string` | — | Extra classes for the root. |

### Usage

```tsx
import { SupportWidget } from "@/components/support-widget";

export function SiteWithSupport({ chat, children }: { chat: SupportChat; children: React.ReactNode }) {
  return (
    <SupportWidget
      data={{
        bot: { name: "Ridge" },
        human: chat.assignee ? { name: chat.assignee.name, role: "Support team" } : undefined,
        visitor: { name: chat.visitor.name },
        // content is any React node — order cards, questions, forms.
        messages: chat.messages.map((m) => ({
          id: m.id,
          role: m.from === "visitor" ? "user" : "assistant",
          author: m.from === "agent" ? chat.assignee?.name : undefined,
          at: m.createdAt,
          content: m.text,
        })),
        quickReplies: chat.messages.length < 2 ? chat.quickReplies : undefined,
        mode: chat.assignee ? "human" : chat.queued ? "waiting" : chat.botTyping ? "typing" : "bot",
        wait: chat.queueEstimate,
        askRating: chat.closed,
        unread: chat.unread,
      }}
      onSend={(text) => chat.send(text)}
      onRate={(rating) => chat.rate(rating)}
      onClose={() => chat.end()}
    >
      {children}
    </SupportWidget>
  );
}
```

### Types

```ts
type SupportPerson = { name: string; avatar?: string; role?: string };

type SupportWidgetData = {
  bot: SupportPerson;
  human?: SupportPerson;               // set message.author to human.name for their turns
  visitor: { name: string };
  messages: ThreadMessage[];           // from chat-thread; content is a ReactNode
  quickReplies?: PromptSuggestion[];   // chips under the last bot message
  mode?: "bot" | "typing" | "waiting" | "human";
  wait?: string;                       // queue estimate, e.g. "~2 min"
  askRating?: boolean;
  unread?: number;                     // badge on the launcher while closed
};

// The widget fills its parent and lays out by its own width: from 28rem the panel
// floats bottom-right over the page, below that it fills the screen.
```

## Handoff Inbox

Where people take over from the bot — escalated conversations by urgency, what the bot already did, reply and hand back.

- Category: Screens
- Docs: https://tuffui.com/components/handoff-inbox
- Install: `npx shadcn@latest add https://tuffui.com/r/handoff-inbox.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| data (required) | `HandoffInboxData` | — | The queue, the open conversation, the bot's summary and drafted replies, and the customer's details. |
| status | `"waiting" \| "active" \| "returned"` | `"waiting"` | Waiting: the bot holds the chat and Take over is offered. Active: the operator replies from the composer. Returned: handed back to the bot. |
| onTakeOver | `() => void` | — | The operator joins the chat. |
| onHandBack | `() => void` | — | The bot takes the chat back. |
| onSend | `(text: string) => void` | — | A reply from the operator. |
| onSelect | `(escalation: Escalation) => void` | — | A conversation picked in the queue (click, or arrow keys and Enter). |
| draft / onDraftChange | `string / (draft: string) => void` | — | Controls the composer text. Picking a drafted reply fills it for editing before sending. |
| queueOpen / defaultQueueOpen / onQueueOpenChange | `boolean / boolean / (open: boolean) => void` | `true` | The queue pane from 56rem wide; toggle with its header button or Cmd/Ctrl + backslash. Narrower, it opens as a drawer. |
| detailsOpen / defaultDetailsOpen / onDetailsOpenChange | `boolean / boolean / (open: boolean) => void` | `true` | The customer details pane from 72rem wide; a drawer below that. |
| className | `string` | — | Extra classes for the root. |

### Usage

```tsx
import { HandoffInbox } from "@/components/handoff-inbox";

export function SupportInbox({ inbox, chat }: { inbox: Inbox; chat: Chat }) {
  return (
    <div className="h-dvh">
      <HandoffInbox
        data={{
          team: inbox.teamName,
          operator: { id: inbox.me.id, name: inbox.me.name },
          bot: { name: "Nora" },
          queue: inbox.escalations, // customer, snippet, reason, waiting minutes…
          activeId: chat.id,
          messages: chat.turns.map((t) => ({
            id: t.id,
            from: t.handoff ? "handoff" : t.author, // "customer" | "bot" | "operator"
            at: t.createdAt,
            content: t.text,
          })),
          summary: chat.botSummary, // { wants, tried, calls }
          suggestions: chat.draftedReplies,
          customer: chat.customer, // plan, orders + orderColumns, notes
        }}
        status={chat.takenBy ? "active" : "waiting"}
        onTakeOver={() => chat.takeOver()}
        onSend={(text) => chat.reply(text)}
        onHandBack={() => chat.handBack()}
        onSelect={(escalation) => inbox.open(escalation.id)}
      />
    </div>
  );
}
```

### Types

```ts
type Escalation = {
  id: string;
  customer: { name: string; avatar?: string };
  snippet: string;  // last thing the customer said
  reason: string;   // why the bot handed off
  tone?: StatusTone;
  urgent?: boolean;
  waiting: number;  // minutes waiting for a person
  assignee?: string; // operator id; drives the "Mine" filter
};

type HandoffMessage = {
  id: string;
  from: "customer" | "bot" | "operator" | "handoff";
  at: string; // ISO
  content: React.ReactNode;
};

type HandoffInboxData = {
  team: string;
  operator: { id: string; name: string; avatar?: string };
  bot: { name: string };
  queue: Escalation[];
  activeId?: string;
  messages: HandoffMessage[];
  summary: { wants: string; tried: string[]; calls?: ToolCall[] };
  suggestions?: PromptSuggestion[];
  customer: {
    name: string; avatar?: string;
    plan: string; planTone?: StatusTone; since: string;
    orders: DataRow[]; orderColumns: DataColumn[];
    notes: Memory[];
  };
};

// The screen fills its parent and lays out by its own width (container queries).
// Give the parent a height.
```

## Streaming Message

Assistant message with token streaming, collapsible reasoning, citation chips and copy / retry actions.

- Category: Conversation
- Docs: https://tuffui.com/components/streaming-message
- Install: `npx shadcn@latest add https://tuffui.com/r/streaming-message.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| data (required) | `StreamingMessageData` | — | The message: content so far, status, optional reasoning, citations and error. Update it on every delta. |
| model | `string` | `"Assistant"` | Name shown in the message header. |
| showHeader | `boolean` | `true` | Show the avatar and model row. Turn it off inside a thread that already labels each turn. |
| onCopy | `(content: string) => void` | — | Called after the content is copied to the clipboard. |
| onRetry | `() => void` | — | Shows Retry on errors and Regenerate when done. |
| className | `string` | — | Extra classes for the root article. |

### Usage

```tsx
import { StreamingMessage, type StreamingMessageData } from "@/components/ui/streaming-message";

export function AssistantTurn({ message }: { message: StreamingMessageData }) {
  // Append text deltas to message.content as they arrive and flip status to
  // "done" on message_stop (or "error" if the stream breaks).
  return (
    <StreamingMessage
      data={message}
      model="Claude Opus 5.5"
      onCopy={(text) => analytics.track("copy_message", { length: text.length })}
      onRetry={() => chat.regenerate(message.id)}
    />
  );
}
```

### Types

```ts
type StreamingMessageData = {
  content: string;          // paragraphs split on blank lines; `code` and **bold** supported
  status: "streaming" | "done" | "error";
  reasoning?: {
    text: string;
    streaming?: boolean;    // shows "Thinking…" and keeps the panel open
    durationMs?: number;    // "Thought for 4s" once finished
  };
  citations?: { id: string; title: string; url: string; source?: string }[];
  error?: string;
};
```

## Agent Status

Live activity line for a working agent — current step, rotating detail, elapsed time and a stop action.

- Category: Conversation
- Docs: https://tuffui.com/components/agent-status
- Install: `npx shadcn@latest add https://tuffui.com/r/agent-status.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| data (required) | `AgentStatusData` | — | The current step, a changing detail, the start time for the timer, finished steps and the run status. |
| onStop | `() => void` | — | Shows a Stop button while the agent is working. |
| maxSteps | `number` | `3` | How many finished steps to show above the current one. 0 shows a single line. |
| className | `string` | — | Extra classes for the root element. |

### Usage

```tsx
import { AgentStatus } from "@/components/ui/agent-status";

export function RunStatus({ run }: { run: AgentRun }) {
  return (
    <AgentStatus
      data={{
        label: run.currentStep.title,      // "Running the test suite"
        detail: run.currentStep.detail,    // "vitest run site"
        startedAt: run.startedAt,
        steps: run.finishedSteps.map((step) => ({
          id: step.id,
          label: step.title,
          durationMs: step.durationMs,
        })),
        status: run.status, // "working" | "done" | "stopped" | "error"
      }}
      maxSteps={3}
      onStop={() => run.abort()}
    />
  );
}
```

### Types

```ts
type AgentStatusData = {
  label: string;
  detail?: string;
  startedAt: number; // ms since epoch
  steps?: { id: string; label: string; durationMs?: number }[];
  status?: "working" | "done" | "stopped" | "error";
};
```

## Message Branches

Switch between regenerated answers and edited prompts — arrows, a mini branch map, and direction-aware swaps.

- Category: Conversation
- Docs: https://tuffui.com/components/message-branches
- Install: `npx shadcn@latest add https://tuffui.com/r/message-branches.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| data (required) | `{ versions: MessageVersion[]; turnsBefore?: number }` | — | Every version of this answer, oldest first. `turnsBefore` is how many turns precede the fork, drawn as dots in the map. |
| index | `number` | — | Controlled index of the visible version. Leave it out to let the component track it. |
| defaultIndex | `number` | `last version` | Initial version when uncontrolled. |
| onIndexChange | `(index: number, version: MessageVersion) => void` | — | Called when the user switches with the arrows, the map or ←/→. Switch the thread to that branch here. |
| onRegenerate | `() => void` | — | Shows a regenerate button next to the switcher. |
| variant | `"inline" \| "map"` | `"inline"` | A ‹ 2 / 3 › switcher under the message, or a branch map with one row per version. |
| className | `string` | — | Extra classes for the root element. |

### Usage

```tsx
import { useState } from "react";
import { MessageBranches } from "@/components/ui/message-branches";

export function AssistantTurn({ turn }: { turn: Turn }) {
  const [index, setIndex] = useState(turn.versions.length - 1);

  return (
    <MessageBranches
      data={{
        turnsBefore: turn.position,
        versions: turn.versions.map((v) => ({
          id: v.id,
          kind: v.editedPrompt ? "edited" : v.parentId ? "regenerated" : "original",
          prompt: v.editedPrompt,
          meta: v.model,
          turnsAfter: v.followUps,
          content: <Markdown>{v.text}</Markdown>,
        })),
      }}
      index={index}
      onIndexChange={(next, version) => {
        setIndex(next);
        thread.checkout(version.id); // later turns follow the chosen branch
      }}
      onRegenerate={() => thread.regenerate(turn.id)}
    />
  );
}
```

### Types

```ts
type MessageVersion = {
  id: string;
  kind: "original" | "regenerated" | "edited";
  content: ReactNode;
  label?: string;      // overrides "Original" / "Regenerated" / "Edited prompt"
  meta?: string;       // e.g. the model, "opus-5.5"
  prompt?: string;     // the edited prompt, for kind "edited"
  turnsAfter?: number; // follow-up turns on this branch, for the map
};
```

## Response Feedback

Thumbs up or down under an answer; a down vote opens reason chips and a note, then settles into a thank-you.

- Category: Conversation
- Docs: https://tuffui.com/components/response-feedback
- Install: `npx shadcn@latest add https://tuffui.com/r/response-feedback.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value | `Feedback` | — | Controlled state: rating, reasons, note and status. Leave it out and the component keeps its own. |
| onValueChange | `(value: Feedback) => void` | — | Called on every change of the controlled state. |
| onRate | `(rating: FeedbackRating) => void` | — | Called on a thumbs up or down, or when a 1–5 rating is picked. Pressing the same thumb again clears it. |
| onSubmit | `(feedback: { rating: FeedbackRating; reasons: string[]; note: string }) => void` | — | Called when the reasons form is sent. Needs at least one reason or a note. |
| onUndo | `() => void` | — | Shows Undo in the thank-you for `undoMs`; reopens the form. |
| undoMs | `number` | `5000` | How long Undo stays after a submit. |
| onCopy | `() => void` | — | Shows a copy button that confirms with a check. |
| onRegenerate | `() => void` | — | Shows a regenerate button. |
| reasons | `string[]` | `["Inaccurate", "Not helpful", "Too long", "Unsafe", "Other"]` | Reason chips, multi-select. |
| variant | `"inline" \| "detailed"` | `"inline"` | Thumbs under an answer that open reasons on a down vote, or a card with a 1–5 rating and reasons always shown. |
| className | `string` | — | Extra classes for the root element. |

### Usage

```tsx
import { ResponseFeedback } from "@/components/ui/response-feedback";

export function AnswerActions({ message }: { message: Message }) {
  return (
    <ResponseFeedback
      onRate={(rating) => analytics.track("answer_rated", { id: message.id, rating })}
      onSubmit={({ rating, reasons, note }) =>
        api.feedback.create({ messageId: message.id, rating, reasons, note })
      }
      onUndo={() => api.feedback.delete({ messageId: message.id })}
      onCopy={() => navigator.clipboard.writeText(message.text)}
      onRegenerate={() => thread.regenerate(message.id)}
    />
  );
}
```

### Types

```ts
type FeedbackRating = "up" | "down" | 1 | 2 | 3 | 4 | 5;

type Feedback = {
  rating: FeedbackRating | null;
  reasons: string[];
  note: string;
  status: "idle" | "open" | "sent";
};
```

## Agent Composer

Prompt input with Ask / Plan / Act modes, a context tray with token counts and messages that queue while the agent works.

- Category: Conversation
- Docs: https://tuffui.com/components/agent-composer
- Install: `npx shadcn@latest add https://tuffui.com/r/agent-composer.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| onSubmit | `(message: ComposerMessage) => void` | — | Called on Enter or Send when the agent is idle, with the text, mode, context items and model. The context tray clears afterwards. |
| status | `"idle" \| "streaming"` | `"idle"` | While streaming, Enter queues the message instead of sending, and a Stop button appears. |
| queue / onQueueChange | `ComposerQueued[]` | — | Messages written while the agent works, shown above the input with remove buttons. Send the next one when a run ends. |
| onStop | `() => void` | — | Called by the Stop button. |
| mode / onModeChange | `"ask" \| "plan" \| "act"` | `"act"` | The Ask / Plan / Act switch in the header, with a hint for the active mode. Act sends with the brand color. |
| showModes | `boolean` | `true` | Hide the mode switch; messages are then sent as act. |
| context / onContextChange | `ComposerContextItem[]` | — | Files and attachments in the context tray, each with a token count and a running total. |
| files | `ComposerFile[]` | — | Candidates for the @ mention menu. Picking one adds it to the tray. |
| commands | `ComposerCommand[]` | — | Slash commands. Typing / at the start opens a filterable menu. |
| models / model / onModelChange | `ComposerModel[] · string` | — | Shown as the model id in the header; clicking switches to the next model. |
| value / onValueChange | `string` | — | Control the text. Uncontrolled when omitted, like mode, context and queue. |
| allowAttachments | `boolean` | `true` | Shows Add context, which opens a file picker (tokens estimated at 4 bytes each). |
| placeholder | `string` | — | Textarea placeholder. |
| className | `string` | — | Extra classes for the root element. |

### Usage

```tsx
import { useEffect, useState } from "react";
import {
  AgentComposer,
  type ComposerFile,
  type ComposerQueued,
} from "@/components/ui/agent-composer";

export function Composer({ files }: { files: ComposerFile[] }) {
  const { status, send, stop } = useAgentRun(); // your runtime
  const [queue, setQueue] = useState<ComposerQueued[]>([]);

  // When a run ends, send the next queued follow-up.
  useEffect(() => {
    if (status !== "idle" || !queue.length) return;
    send({ text: queue[0].text });
    setQueue(queue.slice(1));
  }, [status, queue]);

  return (
    <AgentComposer
      status={status}
      files={files} // @ mention candidates: { id, path, tokens }
      queue={queue}
      onQueueChange={setQueue}
      onSubmit={({ text, mode, context, model }) => send({ text, mode, context, model })}
      onStop={stop}
      models={[
        { id: "opus-5.5", name: "Claude Opus 5.5" },
        { id: "sonnet-5.5", name: "Claude Sonnet 5.5" },
      ]}
      commands={[{ name: "review", description: "Review the current diff" }]}
    />
  );
}
```

### Types

```ts
type ComposerMode = "ask" | "plan" | "act";
type ComposerContextItem = { id: string; name: string; tokens: number };
type ComposerFile = { id: string; path: string; tokens: number };
type ComposerQueued = { id: string; text: string };
type ComposerModel = { id: string; name: string; description?: string };
type ComposerCommand = { name: string; description: string };
type ComposerMessage = {
  text: string;
  mode: ComposerMode;
  context: ComposerContextItem[];
  model?: string;
};
```

## Agent Question

Agent asks with choice cards, marks its own suggestion and reason, and accepts a pick, several picks or free text.

- Category: Conversation
- Docs: https://tuffui.com/components/agent-question
- Install: `npx shadcn@latest add https://tuffui.com/r/agent-question.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| data (required) | `AgentQuestionData` | — | The question, the options as cards, the agent's suggestion with a reason, and whether to allow several answers or free text. |
| status | `"pending" \| "answered" \| "delegated"` | — | Leave unset and the card settles on its own when the user answers. Set it to restore a past thread. |
| answer | `QuestionAnswer` | — | The answer to show once answered. |
| onSubmit | `(answer: QuestionAnswer) => void` | — | Single choice: called as soon as a card is clicked. Multiple: called from the Send pill. |
| onDelegate | `() => void` | — | Shows “Let the agent decide”. The agent should go with its suggestion. |
| onUndo | `() => void` | — | Called from the Undo pill, shown for undoMs after answering. |
| undoMs | `number` | `4000` | How long Undo stays available. |
| selected | `string[]` | — | Controlled selection for multiple-choice questions. |
| onSelectedChange | `(ids: string[]) => void` | — | Called when a card is toggled. |
| agent | `string` | `"Agent"` | Name shown above the question, e.g. “Claude asks”. |
| className | `string` | — | Extra classes for the root element. |

### Usage

```tsx
import { AgentQuestion } from "@/components/ui/agent-question";

export function Clarify({ question, agent }: { question: PendingQuestion; agent: Agent }) {
  return (
    <AgentQuestion
      agent="Claude"
      data={{
        question: question.text,
        options: question.options, // { id, label, description?, icon? }[]
        multiple: question.multiSelect,
        allowOther: true,
        suggested: question.recommendation, // { optionId, reason }
      }}
      onSubmit={(answer) => agent.answer(question.id, answer)}
      onDelegate={() => agent.answer(question.id, { delegate: true })}
      onUndo={() => agent.reopen(question.id)}
    />
  );
}
```

### Types

```ts
type AgentQuestionData = {
  question: string;
  options: { id: string; label: string; description?: string; icon?: Icon }[];
  multiple?: boolean;   // toggle cards, then send
  allowOther?: boolean; // adds a "Something else…" card
  suggested?: { optionId: string; reason: string };
};

type QuestionAnswer = {
  optionIds: string[];
  other?: string;
};

// Keyboard: arrow keys move between cards, Enter or Space picks.
```

## Tool Approval Queue

Triage pending tool calls by risk: select several, grant once, for the session or always, and undo from the resolved log.

- Category: Tools & Approvals
- Docs: https://tuffui.com/components/tool-approval-queue
- Install: `npx shadcn@latest add https://tuffui.com/r/tool-approval-queue.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| data (required) | `ToolApprovalRequest[]` | — | Tool calls waiting on the user. Set a request's status to approved or denied to move it into the resolved log yourself. |
| layout | `"grouped" \| "flat"` | `"grouped"` | Grouped sections requests by risk, high first; flat keeps arrival order. |
| onDecide | `(requests, decision: "approved" \| "denied", scope: GrantScope) => void` | — | Called from a row (with the scope picked there) or from the bulk bar for every selected request (scope once). |
| onUndo | `(request) => void` | — | Called when the user undoes a decision from the resolved log. |
| undoMs | `number` | `5000` | How long Undo stays available after a decision. |
| selected | `string[]` | — | Controlled selection of request ids. Leave unset to let the queue own it. |
| onSelectedChange | `(ids: string[]) => void` | — | Called when rows are selected or cleared. |
| defaultExpanded | `string` | — | Id of a request to open on mount. |
| className | `string` | — | Extra classes for the root section. |

### Usage

```tsx
import { ToolApprovalQueue, type ToolApprovalRequest } from "@/components/ui/tool-approval-queue";

export function Permissions({ requests }: { requests: ToolApprovalRequest[] }) {
  return (
    <ToolApprovalQueue
      data={requests}
      layout="grouped"
      onDecide={(picked, decision, scope) => {
        for (const request of picked) {
          agent.resolveToolCall(request.id, { approved: decision === "approved" });
          if (decision === "approved" && scope !== "once") {
            permissions.allow(request.tool, { scope }); // "session" | "always"
          }
        }
      }}
      onUndo={(request) => agent.reopenToolCall(request.id)}
    />
  );
}
```

### Types

```ts
type GrantScope = "once" | "session" | "always";

type ToolApprovalRequest = {
  id: string;
  tool: string;            // "bash", "fs.write", "slack.post"
  title: string;
  risk: "low" | "medium" | "high";
  agent?: string;
  status?: "pending" | "approved" | "denied";
  scope?: GrantScope;      // for requests you resolve yourself
  payload:
    | { kind: "shell"; command: string; cwd?: string }
    | { kind: "diff"; path: string; lines: { type: "add" | "remove" | "context"; text: string }[] }
    | { kind: "email"; to: string; subject: string; body: string }
    | { kind: "json"; args: Record<string, unknown> };
};

// Keyboard: ↑/↓ move between rows, Space selects, Enter opens a row.
```

## Tool Call Block

Inline chat card for a tool call: name, collapsible JSON args, status, duration and a result preview.

- Category: Tools & Approvals
- Docs: https://tuffui.com/components/tool-call-block
- Install: `npx shadcn@latest add https://tuffui.com/r/tool-call-block.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| data (required) | `ToolCall` | — | The tool call. While status is running the duration counts up on its own; pass durationMs once it settles. |
| defaultOpen | `boolean` | `false` | Start with arguments and result expanded. |
| onRetry | `(call: ToolCall) => void` | — | Shows a Retry button next to the error when the call failed. |
| className | `string` | — | Extra classes for the root element. |

### Usage

```tsx
import { ToolCallBlock, type ToolCall } from "@/components/ui/tool-call-block";

// Map your SDK's tool-use events onto ToolCall and re-render as they change.
function toToolCall(part: ToolUsePart): ToolCall {
  return {
    id: part.id,
    name: part.name,
    args: part.input,
    status: part.state === "output-available" ? "success" : part.state === "error" ? "error" : "running",
    durationMs: part.durationMs,
    result: part.output,
    error: part.errorText,
  };
}

export function ToolCalls({ parts }: { parts: ToolUsePart[] }) {
  return parts.map((part) => (
    <ToolCallBlock
      key={part.id}
      data={toToolCall(part)}
      onRetry={(call) => agent.retryToolCall(call.id)}
    />
  ));
}
```

### Types

```ts
type ToolCall = {
  id: string;
  name: string;                 // "web.search", "fs.read"
  args: Record<string, unknown>;
  status: "pending" | "running" | "success" | "error";
  durationMs?: number;
  result?: string | Record<string, unknown>;
  error?: string;
};
```

## File Changes

Split review: a file tree on one side, hunks on the other — keep or revert each hunk, then apply the result.

- Category: Tools & Approvals
- Docs: https://tuffui.com/components/file-changes
- Install: `npx shadcn@latest add https://tuffui.com/r/file-changes.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| data (required) | `FileChange[]` | — | Files the agent edited, each with its diff hunks. Every hunk needs an id. |
| view | `"split" \| "stacked"` | `"split"` | Split puts a folder tree beside the hunks; stacked swaps the tree for a row of file tabs for narrow columns. |
| onApply (required) | `(selection: HunkSelection) => void` | — | Called with the hunk ids kept per file. Hunks left out were reverted. |
| onHunkChange | `(fileId: string, hunkId: string, keep: boolean) => void` | — | Called whenever a hunk is switched between Keep and Revert. |
| onDiscard | `() => void` | — | Shows a Discard all button. Throw away every change here. |
| applying | `boolean` | `false` | Puts the Apply button in its loading state. |
| selectedId / onSelectedChange | `string / (fileId: string) => void` | — | Control the open file. Leave out to let the component track it. |
| defaultSelectedId | `string` | — | File open on first render when uncontrolled. Defaults to the first file. |
| className | `string` | — | Extra classes for the root element. |

### Usage

```tsx
import { useState } from "react";
import { FileChanges, type FileChange } from "@/components/ui/file-changes";

export function ReviewEdits({ changes }: { changes: FileChange[] }) {
  const [applying, setApplying] = useState(false);

  return (
    <FileChanges
      data={changes}
      applying={applying}
      onApply={async (selection) => {
        // selection maps each file id to the hunk ids the user kept
        setApplying(true);
        await workspace.applyHunks(selection);
        setApplying(false);
      }}
      onDiscard={() => workspace.revertAll()}
    />
  );
}
```

### Types

```ts
type FileChange = {
  id: string;
  path: string;
  from?: string; // previous path when renamed
  status: "added" | "modified" | "deleted" | "renamed";
  hunks: DiffHunk[];
};

type DiffHunk = {
  id: string;
  oldStart: number;
  newStart: number;
  lines: { type: "add" | "remove" | "context"; text: string }[];
};

type HunkSelection = Record<string, string[]>; // file id → kept hunk ids
```

## Terminal Output

Streaming command output with stdout / stderr lines, exit status, duration, copy and stop.

- Category: Tools & Approvals
- Docs: https://tuffui.com/components/terminal-output
- Install: `npx shadcn@latest add https://tuffui.com/r/terminal-output.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| data (required) | `TerminalRun` | — | The command, its output lines and status. While running, the header counts up on its own. |
| onStop | `() => void` | — | Shows a Stop button while the command runs. Kill the process here. |
| onCopy | `(text: string) => void` | — | Called with the full output after it is copied to the clipboard. |
| maxHeight | `number` | `280` | Height in px after which the output scrolls. Scrolling up pauses auto-follow and shows Jump to latest. |
| className | `string` | — | Extra classes for the root section. |

### Usage

```tsx
import { TerminalOutput, type TerminalRun } from "@/components/ui/terminal-output";

export function CommandOutput({ run }: { run: TerminalRun }) {
  // Append lines as the sandbox streams them:
  // { text: chunk, stream: "stdout" | "stderr" }
  return (
    <TerminalOutput
      data={run}
      onStop={() => sandbox.kill(run.command)}
      onCopy={(text) => analytics.track("terminal_copied", { bytes: text.length })}
    />
  );
}
```

### Types

```ts
type TerminalRun = {
  command: string;
  cwd?: string;
  lines: TerminalLine[];
  status: "running" | "success" | "failed";
  exitCode?: number;
  durationMs?: number; // final duration
};

type TerminalLine = {
  text: string;
  stream?: "stdout" | "stderr" | "info"; // stderr is tinted and marked
};
```

## MCP Servers

Connected MCP servers with status, auth prompts and reconnect — expand one to switch individual tools on or off.

- Category: Tools & Approvals
- Docs: https://tuffui.com/components/mcp-servers
- Install: `npx shadcn@latest add https://tuffui.com/r/mcp-servers.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| data (required) | `McpServer[]` | — | Servers in display order, each with its status and tools. |
| view | `"servers" \| "tools"` | `"servers"` | Expandable servers with their tools, or one searchable list of every tool grouped by server. |
| onToggleTool | `(serverId: string, tool: string, enabled: boolean) => void` | — | Called when a tool's switch flips. Tools are disabled unless the server is connected. |
| onToggleServer | `(serverId: string, enabled: boolean) => void` | — | Called by the All tools switch inside an expanded server. |
| onAuthorize | `(server: McpServer) => void` | — | Called by the Authorize button on servers that need auth. |
| onReconnect | `(server: McpServer) => void` | — | Called by the Reconnect button on servers in the error state. |
| defaultExpanded | `string` | — | Id of the server that starts expanded. |
| className | `string` | — | Extra classes for the root element. |

### Usage

```tsx
import { McpServers } from "@/components/ui/mcp-servers";

export function Connectors({ servers }: { servers: McpServer[] }) {
  return (
    <McpServers
      data={servers}
      onToggleTool={(serverId, tool, enabled) =>
        mcp.setToolEnabled(serverId, tool, enabled)
      }
      onToggleServer={(serverId, enabled) => mcp.setAllTools(serverId, enabled)}
      onAuthorize={(server) => mcp.startOAuth(server.id)} // opens the provider's consent page
      onReconnect={(server) => mcp.restart(server.id)}
    />
  );
}
```

### Types

```ts
type McpServer = {
  id: string;
  name: string;
  transport: "stdio" | "http";
  status: "connected" | "connecting" | "needs-auth" | "error";
  error?: string; // shown on error rows
  tools: { name: string; description?: string; enabled: boolean }[];
};
```

## Background Agents Panel

Agents working in the background as a grid of live tiles or a compact dock that expands into the selected agent.

- Category: Planning & Execution
- Docs: https://tuffui.com/components/background-agents
- Install: `npx shadcn@latest add https://tuffui.com/r/background-agents.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| data (required) | `BackgroundAgent[]` | — | Agents to show, in your order. Each tile or avatar fills from the bottom as progress grows. |
| layout | `"grid" \| "dock"` | `"grid"` | Grid shows a live tile per agent; dock is a row of avatars that expands into the selected agent. |
| onPause / onResume / onCancel / onOpen | `(agent: BackgroundAgent) => void` | — | Each shows its action on the tile (on hover or focus) or in the dock strip. Update the agent's status yourself. |
| onReview | `(agent: BackgroundAgent) => void` | — | Called from the Review action of an agent with status waiting. Falls back to onOpen. |
| selectedId | `string \| null` | — | Controls which agent the dock expands; null collapses it. |
| onSelect | `(agent: BackgroundAgent \| null) => void` | — | Called when the viewer picks or collapses an agent in the dock. |
| className | `string` | — | Extra classes for the root section. |

### Usage

```tsx
import { BackgroundAgents, type BackgroundAgent } from "@/components/ui/background-agents";

export function AgentsPanel({ agents }: { agents: BackgroundAgent[] }) {
  return (
    <BackgroundAgents
      data={agents}
      onPause={(agent) => runtime.pause(agent.id)}
      onResume={(agent) => runtime.resume(agent.id)}
      onCancel={(agent) => runtime.cancel(agent.id)}
      onOpen={(agent) => router.push(`/agents/${agent.id}`)}
      onReview={(agent) => router.push(`/agents/${agent.id}/review`)}
    />
  );
}
```

### Types

```ts
type BackgroundAgent = {
  id: string;
  name: string;
  task: string;
  status: "queued" | "running" | "waiting" | "paused" | "done" | "failed" | "cancelled";
  progress: number;  // 0–1
  action?: string;   // what it is doing right now
  elapsedMs: number;
};
```

## Checkpoint Timeline

Checkpoints the agent made along the way — scrub through turns, see what changed, restore to any point.

- Category: Planning & Execution
- Docs: https://tuffui.com/components/checkpoint-timeline
- Install: `npx shadcn@latest add https://tuffui.com/r/checkpoint-timeline.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| data (required) | `Checkpoint[]` | — | Checkpoints oldest first. The last one is treated as the current state. |
| variant | `"timeline" \| "compact"` | `"timeline"` | A scrubber with a preview of the hovered or selected checkpoint, or a single row with previous / next. |
| selectedId | `string` | — | Controlled selection. Defaults to the latest checkpoint. |
| onSelect | `(checkpoint: Checkpoint) => void` | — | Called on click, focus or arrow keys (← → Home End). |
| onRestore | `(checkpoint: Checkpoint) => void` | — | Called after the inline confirmation. Remove the later checkpoints from data — the track trims with an animation. |
| confirming | `boolean` | — | Controls the confirmation step. Leave unset to let the component own it. |
| onConfirmingChange | `(confirming: boolean) => void` | — | Called when the user opens or cancels the confirmation. |
| className | `string` | — | Extra classes for the root element. |

### Usage

```tsx
import { CheckpointTimeline } from "@/components/ui/checkpoint-timeline";

export function SessionHistory({ session }: { session: AgentSession }) {
  return (
    <CheckpointTimeline
      data={session.checkpoints.map((c) => ({
        id: c.id,
        label: c.summary,
        at: formatRelative(c.createdAt),
        files: c.diffStat, // [{ path, additions, deletions }]
      }))}
      onRestore={async (checkpoint) => {
        await session.rewind(checkpoint.id); // reverts files and drops later turns
      }}
    />
  );
}
```

### Types

```ts
type Checkpoint = {
  id: string;
  label: string; // what the turn did
  at: string; // display time, e.g. "4m ago"
  files: { path: string; additions: number; deletions: number }[];
};
```

## Run Trace

Flame graph of an agent run with click-to-zoom spans, plus a breakdown of where time, tokens and cost went.

- Category: Observability
- Docs: https://tuffui.com/components/run-trace
- Install: `npx shadcn@latest add https://tuffui.com/r/run-trace.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| data (required) | `{ spans: TraceSpan[]; elapsedMs: number }` | — | Spans of one run with offsets from its start. elapsedMs drives running spans and the time axis. |
| view | `"flame" \| "breakdown"` | `"flame"` | Flame is a zoomable flame graph: click a span to fill the width with it, Esc or the breadcrumb to zoom out. Breakdown totals time, tokens or cost per tool and model. |
| onZoom | `(span: TraceSpan \| null) => void` | — | Called when the flame graph zooms into a span, or back to the whole run. |
| className | `string` | — | Extra classes for the root section. |

### Usage

```tsx
import { RunTrace, type TraceSpan } from "@/components/ui/run-trace";

// Map your tracer's spans (OpenTelemetry, Langfuse, agent SDK events) to TraceSpan.
export function Trace({ spans, elapsedMs }: { spans: TraceSpan[]; elapsedMs: number }) {
  return (
    <RunTrace
      data={{ spans, elapsedMs }}
      onZoom={(span) => analytics.track("trace_zoom", { span: span?.name })}
    />
  );
}

// While the run is live, leave endMs undefined on open spans and
// re-render with a growing elapsedMs (e.g. from requestAnimationFrame).
```

### Types

```ts
type TraceSpan = {
  id: string;
  parentId?: string;       // nests the span under another one
  name: string;
  kind: "llm" | "tool" | "agent" | "retrieval";
  startMs: number;         // offset from the start of the run
  endMs?: number;          // undefined while running
  model?: string;
  tokens?: { input: number; output: number };
  costUsd?: number;
  status?: "ok" | "error";
};
```

## Eval Results

An eval run as a grid of cases — pass, fail or regressed vs the baseline — with per-case input, expected and actual.

- Category: Observability
- Docs: https://tuffui.com/components/eval-results
- Install: `npx shadcn@latest add https://tuffui.com/r/eval-results.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| data (required) | `{ suite: string; label?: string; cases: EvalCase[]; baselinePassRate?: number; metrics?: EvalMetric[] }` | — | The suite, its cases in run order and, for the delta and the compare view, the baseline pass rate and metrics. |
| view | `"grid" \| "compare"` | `"grid"` | A square per case, or baseline vs candidate bars per metric plus the regressed cases. |
| filter | `"all" \| "failed" \| "regressed" \| "improved"` | — | Controlled filter. Non-matching cases dim instead of disappearing, so the grid stays put. |
| onFilterChange | `(filter) => void` | — | Called when a filter pill is picked. |
| selectedId | `string \| null` | — | Controlled selection. The selected case shows its input, expected and actual output below. |
| onSelectCase | `(testCase: EvalCase) => void` | — | Called on click or Enter. Arrow keys, Home and End move between cases. |
| className | `string` | — | Extra classes for the root element. |

### Usage

```tsx
import { EvalResults } from "@/components/ui/eval-results";

export function EvalRun({ run }: { run: EvalRun }) {
  return (
    <EvalResults
      data={{
        suite: run.suite,
        label: `${run.candidate} vs ${run.baseline}`,
        // status: "pending" | "running" | "pass" | "fail" | "regressed" | "improved"
        cases: run.cases,
        baselinePassRate: run.baselinePassRate,
        metrics: [
          { id: "acc", label: "Accuracy", baseline: 0.85, candidate: 0.88, better: "higher" },
          { id: "p50", label: "Latency p50", baseline: 1840, candidate: 1320, better: "lower" },
        ],
      }}
      onSelectCase={(c) => console.log(c.id)}
    />
  );
}
```

### Types

```ts
type EvalCase = {
  id: string;
  name: string;
  status: "pending" | "running" | "pass" | "fail" | "regressed" | "improved";
  score?: number; // 0–1
  input?: string;
  expected?: string;
  actual?: string;
  reason?: string;
};

type EvalMetric = {
  id: string;
  label: string;
  baseline: number;
  candidate: number;
  better: "higher" | "lower";
  format?: (value: number) => string;
};
```

## Context Window Meter

Token usage by segment — system, history, files, tools — with a near-limit warning and a compact action.

- Category: Settings & Usage
- Docs: https://tuffui.com/components/context-window-meter
- Install: `npx shadcn@latest add https://tuffui.com/r/context-window-meter.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| data (required) | `{ limit: number; segments: ContextSegment[]; model?: string }` | — | The model's context limit, token counts per segment in fill order, and an optional model name shown as a tag. |
| warnAt | `number` | `0.8` | Share of the limit where the tinted warning zone starts. Past it the count turns orange and the inline row shows Compact. |
| onCompact | `() => void` | — | Shows a Compact button (always in the card, past `warnAt` inline). Summarize or drop context here. |
| compacting | `boolean` | `false` | Puts the Compact button in its loading state. |
| variant | `"card" \| "inline"` | `"card"` | A panel with a 100-cell grid (1% per cell) and a legend, or a 20-cell row for a composer footer. |
| className | `string` | — | Extra classes for the root element. |

### Usage

```tsx
import { useState } from "react";
import { ContextWindowMeter } from "@/components/ui/context-window-meter";

export function ContextUsage({ usage }: { usage: Usage }) {
  const [compacting, setCompacting] = useState(false);

  return (
    <ContextWindowMeter
      data={{
        limit: 200_000,
        model: "opus-5.5",
        segments: [
          { id: "history", label: "Conversation", tokens: usage.history },
          { id: "files", label: "Workspace files", tokens: usage.files },
          { id: "tools", label: "MCP tools", tokens: usage.tools, pinned: true },
          { id: "system", label: "Instructions", tokens: usage.system, pinned: true },
        ],
      }}
      warnAt={0.8}
      compacting={compacting}
      onCompact={async () => {
        setCompacting(true);
        await agent.compact(); // summarize older turns
        setCompacting(false);
      }}
    />
  );
}
```

### Types

```ts
type ContextSegment = {
  id: string;
  label: string;
  tokens: number;
  detail?: string; // secondary text, e.g. "4 open"
  pinned?: boolean; // shows a lock next to the label
  color?: string; // any CSS color; defaults to the built-in palette
};
```

## Memory Panel

What the agent remembers about the user and project — search, scopes, inline edit and forget.

- Category: Settings & Usage
- Docs: https://tuffui.com/components/memory-panel
- Install: `npx shadcn@latest add https://tuffui.com/r/memory-panel.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| data (required) | `Memory[]` | — | Memories in display order. Set isNew on ones added this session. |
| onEdit | `(memory, text: string) => void` | — | Called when an inline edit is saved with Enter. Esc cancels. |
| onForget | `(memory) => void` | — | Called once the undo window closes. The row hides immediately and shows an Undo pill. |
| onUndo | `(memory) => void` | — | Called when the user restores a memory within the undo window. |
| undoMs | `number` | `5000` | How long the Undo pill stays before the Forget is committed. |
| variant | `"panel" \| "compact"` | `"panel"` | A panel with search and scope filters, or a dense list without them. |
| title | `string` | `"Memory"` | Heading and accessible name of the panel. |
| className | `string` | — | Extra classes for the root element. |

### Usage

```tsx
import { MemoryPanel } from "@/components/ui/memory-panel";

export function AgentMemory({ memories }: { memories: Memory[] }) {
  return (
    <MemoryPanel
      data={memories}
      onEdit={(memory, text) => api.memories.update(memory.id, { text })}
      // Called after the undo window closes, so a quick Undo never hits the server.
      onForget={(memory) => api.memories.delete(memory.id)}
    />
  );
}
```

### Types

```ts
type Memory = {
  id: string;
  text: string;
  scope: "user" | "project" | "session";
  source?: string; // e.g. "from chat · 2d ago"
  pinned?: boolean;
  isNew?: boolean; // shows a "New" pill
};
```

## Usage Summary

Tokens and cost over time, split by model, against a monthly budget.

- Category: Settings & Usage
- Docs: https://tuffui.com/components/usage-summary
- Install: `npx shadcn@latest add https://tuffui.com/r/usage-summary.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| data (required) | `{ days: UsageDay[]; models: UsageModel[]; previousCost?: number; budget?: { limit: number; label?: string } }` | — | One entry per day with tokens and cost per model. previousCost adds a delta pill; budget adds a budget bar. |
| currency | `string` | `"USD"` | ISO 4217 code used to format costs. |
| warnAt | `number` | `0.8` | Share of the budget past which the budget bar turns into a warning. |
| onSelectDay | `(day: UsageDay) => void` | — | Called when a bar is clicked or activated with Enter / Space. |
| title | `string` | `"Usage"` | Heading and accessible name of the card. |
| className | `string` | — | Extra classes for the root element. |

### Usage

```tsx
import { UsageSummary } from "@/components/ui/usage-summary";

export function Billing({ report }: { report: UsageReport }) {
  return (
    <UsageSummary
      data={{
        models: [
          { id: "opus", name: "Claude Opus 5.5" },
          { id: "sonnet", name: "Claude Sonnet 5.5" },
        ],
        // One entry per day: { date: "2026-11-03", byModel: { opus: { tokens, cost } } }
        days: report.days,
        previousCost: report.previousPeriodCost,
        budget: { limit: 500, label: "Monthly budget" },
      }}
      currency="USD"
      onSelectDay={(day) => router.push(`/usage/${day.date}`)}
    />
  );
}
```

### Types

```ts
type UsageModel = {
  id: string;
  name: string;
  color?: string; // any CSS color; defaults to the built-in palette
};

type UsageDay = {
  date: string; // ISO date, e.g. "2026-11-03"
  byModel: Record<string, { tokens: number; cost: number }>;
};
```

## Rate Limits

Requests and tokens per minute as refilling buckets, with a retry-after countdown and queued calls when throttled.

- Category: Settings & Usage
- Docs: https://tuffui.com/components/rate-limits
- Install: `npx shadcn@latest add https://tuffui.com/r/rate-limits.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| data (required) | `{ model?: string; limits: RateLimit[]; queued?: QueuedCall[]; retryAfterMs?: number }` | — | One gauge per limit. retryAfterMs (or a bucket at zero) switches to the throttled state; both timers count down locally. |
| onRetry | `() => void` | — | Called by Retry now, which unlocks when the retry-after countdown ends. |
| className | `string` | — | Extra classes for the root element. |

### Usage

```tsx
import { RateLimits } from "@/components/ui/rate-limits";

// Fill it from the rate-limit headers on each API response.
export function Limits({ headers, queue, retryAfter }: Props) {
  return (
    <RateLimits
      data={{
        model: "opus-5.5 · Tier 3",
        limits: [
          {
            id: "req",
            label: "Requests",
            limit: Number(headers["requests-limit"]),
            remaining: Number(headers["requests-remaining"]),
            resetsInMs: msUntil(headers["requests-reset"]),
          },
          // …input and output tokens the same way
        ],
        queued: queue, // calls your client is holding back
        retryAfterMs: retryAfter * 1000, // from a 429's retry-after header
      }}
      onRetry={() => client.flushQueue()}
    />
  );
}
```

### Types

```ts
type RateLimit = {
  id: string;
  label: string; // shown as "<label> / min"
  limit: number;
  remaining: number;
  resetsInMs: number;
};

type QueuedCall = { id: string; label: string; tokens?: number };
```

## Chat Thread

The conversation itself — user and assistant turns, grouping, date dividers, unread marker and a jump-to-latest pill.

- Category: Conversation
- Docs: https://tuffui.com/components/chat-thread
- Install: `npx shadcn@latest add https://tuffui.com/r/chat-thread.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| data (required) | `{ messages: ThreadMessage[]; unreadFrom?: string }` | — | Turns in order. Consecutive turns from one side within five minutes share a header; `unreadFrom` puts an Unread divider before that message. |
| density | `"default" \| "dense"` | `"default"` | Dense drops avatars and tightens spacing for side panels. |
| agentName | `string` | `"Assistant"` | Header name for assistant turns. |
| userName | `string` | `"You"` | Header name for user turns. |
| renderAvatar | `(message: ThreadMessage) => ReactNode` | — | Custom avatar; defaults to a sparkle for the agent and an initial for people. |
| height | `number \| string` | `420 (100% when bare)` | Height of the scroll area. The thread follows new content while you're at the bottom and shows Jump to latest when you scroll up. |
| bare | `boolean` | `false` | Drop the shell and panel so the thread is just the scroll area and fills its parent — for full screens where the thread is the page. |
| footer | `ReactNode` | — | Rendered after the last message inside the scroll area, e.g. follow-up chips. |
| bottomInset | `number` | `0` | Pixels kept free at the bottom for a composer that floats over the thread; Jump to latest sits above it. |
| contentClassName | `string` | — | Classes for the message column, e.g. `mx-auto max-w-3xl`. |
| className | `string` | — | Extra classes for the shell. |

### Usage

```tsx
import { ChatThread } from "@/components/ui/chat-thread";
import { StreamingMessage } from "@/components/ui/streaming-message";

export function Conversation({ messages, lastReadId }: Props) {
  return (
    <ChatThread
      agentName="Claude"
      data={{
        unreadFrom: lastReadId,
        messages: messages.map((m) => ({
          id: m.id,
          role: m.role,
          at: m.createdAt,
          streaming: m.status === "streaming",
          // Any node: plain text, a StreamingMessage, tool calls, charts…
          content: m.role === "assistant" ? <StreamingMessage data={m} /> : m.text,
        })),
      }}
    />
  );
}
```

### Types

```ts
type ThreadMessage = {
  id: string;
  role: "user" | "assistant";
  content: ReactNode;
  at: string;          // ISO timestamp
  author?: string;
  streaming?: boolean; // shows a caret and keeps the thread pinned while it grows
};
```

## User Message

A sent prompt with attachments, edit-in-place and resend, copy, and a delivery state.

- Category: Conversation
- Docs: https://tuffui.com/components/user-message
- Install: `npx shadcn@latest add https://tuffui.com/r/user-message.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| data (required) | `UserMessageData` | — | The prompt text, attachments, display time and delivery status. |
| onEdit | `(text: string) => void` | — | Save & resend from the inline editor (Enter saves, Shift+Enter adds a line, Esc cancels). The edit action is hidden without it. |
| onRetry | `() => void` | — | Shows a Retry button when the status is failed. |
| onCopy | `(text: string) => void` | — | Called after the text is copied to the clipboard. |
| className | `string` | — | Extra classes for the root. |

### Usage

```tsx
import { UserMessage } from "@/components/ui/user-message";

export function Prompt({ message }: { message: Message }) {
  return (
    <UserMessage
      data={{
        id: message.id,
        content: message.text,
        attachments: message.files,
        sentAt: formatTime(message.createdAt),
        status: message.status, // "sending" | "sent" | "failed"
        edited: message.edited,
      }}
      onEdit={(text) => chat.editAndResend(message.id, text)}
      onRetry={() => chat.resend(message.id)}
    />
  );
}
```

### Types

```ts
type UserMessageData = {
  id: string;
  content: string;
  attachments?: { id: string; name: string; kind: "image" | "file"; size?: number; previewUrl?: string }[];
  sentAt?: string;            // display time, e.g. "14:02"
  status?: "sending" | "sent" | "failed";
  edited?: boolean;
};
```

## Conversation List

Chat history for a sidebar — search, pinned and dated groups, rename inline, archive and delete with undo.

- Category: Conversation
- Docs: https://tuffui.com/components/conversation-list
- Install: `npx shadcn@latest add https://tuffui.com/r/conversation-list.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| data (required) | `Conversation[]` | — | Chats, grouped into Pinned, Today, Yesterday, Previous 7 days and Older. |
| activeId | `string` | — | The open chat, marked with aria-current. |
| onSelect | `(conversation) => void` | — | Click or Enter on a row. Arrow keys move between rows. |
| onNew | `() => void` | — | Shows a New chat button in the header. |
| onRename | `(conversation, title) => void` | — | Inline rename from the row menu: Enter or blur saves, Esc cancels. |
| onPin | `(conversation, pinned) => void` | — | Pin or unpin from the row menu. |
| onArchive / onDelete | `(conversation) => void` | — | The row hides at once with an Undo pill; the callback runs when the undo window closes. |
| undoMs | `number` | `5000` | How long Undo stays available. |
| variant | `"sidebar" \| "compact"` | `"sidebar"` | Compact lists titles only, without search or group labels. |
| now | `string` | — | Reference time for the date groups (ISO); defaults to now. |
| headerAction | `ReactNode` | — | Extra control in the header next to New chat, e.g. a hide-sidebar toggle. |
| className | `string` | — | Extra classes for the shell. |

### Usage

```tsx
import { ConversationList } from "@/components/ui/conversation-list";

export function ChatSidebar({ chats, activeId }: Props) {
  return (
    <ConversationList
      data={chats.map((c) => ({
        id: c.id,
        title: c.title,
        updatedAt: c.lastMessageAt,
        pinned: c.pinned,
        running: c.status === "running",
      }))}
      activeId={activeId}
      onSelect={(c) => router.push(`/chat/${c.id}`)}
      onNew={() => router.push("/chat/new")}
      onRename={(c, title) => api.rename(c.id, title)}
      onPin={(c, pinned) => api.pin(c.id, pinned)}
      onArchive={(c) => api.archive(c.id)} // after the undo window
      onDelete={(c) => api.delete(c.id)}
    />
  );
}
```

### Types

```ts
type Conversation = {
  id: string;
  title: string;
  updatedAt: string; // ISO
  pinned?: boolean;
  running?: boolean; // shows a pulsing dot while the agent works
};
```

## Prompt Suggestions

Starter prompts for an empty chat and follow-up chips under an answer.

- Category: Conversation
- Docs: https://tuffui.com/components/prompt-suggestions
- Install: `npx shadcn@latest add https://tuffui.com/r/prompt-suggestions.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| data (required) | `PromptSuggestion[]` | — | Suggestions in display order. New ids animate in, old ones out. |
| variant | `"cards" \| "chips"` | `"cards"` | Cards with icon and hint for an empty chat; wrapping chips for follow-ups. |
| onSelect (required) | `(suggestion, prompt: string) => void` | — | Called with the suggestion and the text to send (`prompt` or the title). |
| onRefresh | `() => void` | — | Shows a refresh button after the chips. |
| refreshing | `boolean` | `false` | Spins the refresh icon and disables the chips. |
| heading | `string` | — | Label above the suggestions; also their accessible name. |
| className | `string` | — | Extra classes for the root. |

### Usage

```tsx
import { PromptSuggestions } from "@/components/ui/prompt-suggestions";
import { ChartBar, Globe } from "@phosphor-icons/react";

// Empty chat
<PromptSuggestions
  heading="What should we work on?"
  data={[
    { id: "i18n", icon: Globe, title: "Localize the onboarding flow", hint: "German and Japanese" },
    { id: "chart", icon: ChartBar, title: "Chart last month's signups", hint: "By plan" },
  ]}
  onSelect={(_, prompt) => chat.send(prompt)}
/>

// Follow-ups under an answer
<PromptSuggestions
  variant="chips"
  data={answer.followUps}
  refreshing={loading}
  onRefresh={() => chat.suggestMore(answer.id)}
  onSelect={(_, prompt) => chat.send(prompt)}
/>
```

### Types

```ts
type PromptSuggestion = {
  id: string;
  title: string;
  hint?: string;   // second line on cards
  icon?: Icon;     // from @phosphor-icons/react
  prompt?: string; // text to send; defaults to the title
};
```

## Attachment Preview

Images and files attached to a prompt — thumbnails, type and size, upload progress, retry and remove.

- Category: Conversation
- Docs: https://tuffui.com/components/attachment-preview
- Install: `npx shadcn@latest add https://tuffui.com/r/attachment-preview.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| data (required) | `Attachment[]` | — | Files in display order. Images with a src render as thumbnails that open an enlarged view; everything else renders as a file tile. |
| onRemove | `(attachment) => void` | — | Shows a remove button on each tile (on hover, focus, or always on touch). |
| onRetry | `(attachment) => void` | — | Shows Retry on failed file uploads. |
| onOpen | `(attachment \| null) => void` | — | Called when an image opens in the enlarged view and with null when it closes. |
| className | `string` | — | Extra classes for the root element. |

### Usage

```tsx
import { AttachmentPreview, type Attachment } from "@/components/ui/attachment-preview";

export function ComposerAttachments({ files, setFiles }: {
  files: Attachment[];
  setFiles: (files: Attachment[]) => void;
}) {
  return (
    <AttachmentPreview
      data={files} // { id, name, size, type, src?, status, progress }
      onRemove={(file) => setFiles(files.filter((f) => f.id !== file.id))}
      onRetry={(file) => upload(file.id)}
    />
  );
}
```

### Types

```ts
type Attachment = {
  id: string;
  name: string;
  size: number;          // bytes
  type: string;          // MIME type
  src?: string;          // images only
  alt?: string;
  status?: "uploading" | "ready" | "failed";
  progress?: number;     // 0–1 while uploading
  error?: string;
};
```

## Code Block

Code in an answer — filename, language, line numbers, wrap toggle, copy and collapse for long snippets.

- Category: Conversation
- Docs: https://tuffui.com/components/code-block
- Install: `npx shadcn@latest add https://tuffui.com/r/code-block.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| data (required) | `CodeBlockData` | — | The code, its language, an optional filename and lines to highlight. |
| collapseAfter | `number` | `14` | Longer code collapses to this many lines behind a “Show all N lines” control. |
| showLineNumbers | `boolean` | `true` | Line numbers in a sticky gutter. |
| defaultWrap | `boolean` | `false` | Start with soft wrap on; the header toggle switches it. |
| onCopy | `(code: string) => void` | — | Called after the code is copied to the clipboard. |
| className | `string` | — | Extra classes for the shell. |

### Usage

```tsx
import { CodeBlock } from "@/components/ui/code-block";

export function AnswerCode({ block }: { block: { code: string; lang: string; file?: string } }) {
  return (
    <CodeBlock
      data={{ code: block.code, language: block.lang as "ts", filename: block.file }}
      collapseAfter={16}
      onCopy={() => analytics.track("code_copied")}
    />
  );
}
```

### Types

```ts
type CodeLanguage = "ts" | "tsx" | "js" | "json" | "bash" | "python" | "text";

type CodeBlockData = {
  code: string;
  language?: CodeLanguage; // drives the built-in tokenizer
  filename?: string;
  highlight?: number[];    // 1-based line numbers
};
```

## Source List

Citations behind an answer — numbered footnotes with hover previews and a panel of every source used.

- Category: Conversation
- Docs: https://tuffui.com/components/source-list
- Install: `npx shadcn@latest add https://tuffui.com/r/source-list.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| data (required) | `SourceListData` | — | Sources in citation order, plus the answer text with [n] markers (footnotes) or the claims each source supports (panel). |
| variant | `"footnotes" \| "panel"` | `"footnotes"` | Inline markers with hover previews and a numbered list, or a panel grouped by site showing which claims each source backs. |
| onOpen | `(source: Source) => void` | — | Called when a source link is opened. |
| className | `string` | — | Extra classes for the root element. |

### Usage

```tsx
import { SourceList } from "@/components/ui/source-list";

// The model writes markers like [1] or [2, 3] that index into the sources it used.
export function CitedAnswer({ answer }: { answer: { text: string; sources: Source[] } }) {
  return <SourceList data={{ text: answer.text, sources: answer.sources }} />;
}

export function SourcesTab({ answer }: { answer: Answer }) {
  return (
    <SourceList
      variant="panel"
      data={{ sources: answer.sources, claims: answer.claims }}
      onOpen={(source) => analytics.track("source_opened", { url: source.url })}
    />
  );
}
```

### Types

```ts
type Source = { id: string; title: string; url: string; snippet?: string; date?: string };

type SourceListData = {
  sources: Source[];
  text?: string; // "… [1] … [2, 3]"
  claims?: { id: string; text: string; sourceIds: string[] }[];
};
```

## Chart Card

A chart the agent answers with — bar, line, area or donut, with tooltips, legend toggles and animated data.

- Category: Interactive Answers
- Docs: https://tuffui.com/components/chart-card
- Install: `npx shadcn@latest add https://tuffui.com/r/chart-card.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| data (required) | `{ labels: string[]; series: ChartSeries[] }` | — | One label per point and up to four series. Series keep their color when others are toggled off. |
| type | `"bar" \| "line" \| "area" \| "donut"` | `"bar"` | Grouped bars, lines, filled areas, or a donut where each series is one slice. |
| title (required) | `string` | — | Header title, also the chart's accessible name. |
| subtitle | `string` | — | Secondary line under the title. |
| total | `string` | — | Headline value in the header; rolls when it changes. |
| format | `(value: number) => string` | — | Formats axis ticks, tooltip values and the donut center. Defaults to 1.2k / 3.4M. |
| partialLast | `boolean` | `false` | Stripes the last bar, for a period that is still in progress. |
| onSelect | `(index: number) => void` | — | Called when a point or slice is hovered, clicked or reached with the arrow keys. |
| className | `string` | — | Extra classes for the root element. |

### Usage

```tsx
import { ChartCard } from "@/components/ui/chart-card";

// Render a chart when a tool returns a time series.
export function SignupsAnswer({ result }: { result: SignupsResult }) {
  return (
    <ChartCard
      type="bar"
      title="Weekly signups"
      subtitle="Self-serve vs. sales-led"
      total={result.total.toLocaleString()}
      partialLast // the current week isn't over
      data={{
        labels: result.weeks,
        series: [
          { id: "self", label: "Self-serve", values: result.selfServe },
          { id: "sales", label: "Sales-led", values: result.salesLed },
        ],
      }}
      onSelect={(index) => console.log(result.weeks[index])}
    />
  );
}
```

### Types

```ts
type ChartSeries = {
  id: string;
  label: string;
  values: number[]; // one per label; a donut slice is their sum
  color?: string;   // defaults to blue, teal, purple, ochre by position
};

// Keyboard: focus the chart, then ← → Home End move between points, Esc clears.
// Screen readers get a summary label and a hidden data table.
```

## Dot Histogram

A distribution as stacked dots — every sample visible, median and p95 marked, samples past a limit such as a timeout flagged.

- Category: Interactive Answers
- Docs: https://tuffui.com/components/dot-histogram
- Install: `npx shadcn@latest add https://tuffui.com/r/dot-histogram.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| values (required) | `number[]` | — | Raw samples. The component bins them and works out the median and p95. |
| title (required) | `string` | — | Header title. |
| subtitle | `string` | — | Secondary line under the title. |
| threshold | `number` | — | Samples at or above it are drawn red and counted in the footer. |
| thresholdLabel | `string` | `"over limit"` | What a flagged sample means, e.g. “timed out”. |
| bins | `number` | `48` | Number of columns. |
| unit | `string` | `"samples"` | Plural name for one sample, used in the header, tooltip and footer. |
| format | `(value: number) => string` | — | Formats axis labels, the median, p95 and tooltip ranges. |
| onSelect | `(bin: DotHistogramBin) => void` | — | Called when a column is hovered or reached with the arrow keys. |
| className | `string` | — | Extra classes for the root element. |

### Usage

```tsx
import { DotHistogram } from "@/components/ui/dot-histogram";

// Show how response times spread when the agent reports on recent runs.
export function LatencyAnswer({ runs }: { runs: Run[] }) {
  return (
    <DotHistogram
      title="Response time"
      subtitle={`Last ${runs.length} runs · timeout 15 s`}
      values={runs.map((r) => r.seconds)}
      threshold={15}
      thresholdLabel="timed out"
      unit="runs"
      format={(v) => `${+v.toFixed(1)}s`}
      onSelect={(bin) => openRuns(bin.from, bin.to)}
    />
  );
}
```

### Types

```ts
type DotHistogramBin = { from: number; to: number; count: number; flagged: boolean };

// Tall columns switch to one dot per group ("1 dot = 3 runs") so the chart keeps its height.
// Keyboard: focus the chart, then ← → Home End move between filled columns, Esc clears.
```

## Tick Gauge

A meter drawn as ticks around an arc, with a target marker and the shortfall to it in red — success rates, SLOs, budgets.

- Category: Interactive Answers
- Docs: https://tuffui.com/components/tick-gauge
- Install: `npx shadcn@latest add https://tuffui.com/r/tick-gauge.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| value (required) | `number` | — | Current value, 0–1. |
| title (required) | `string` | — | Header title. |
| subtitle | `string` | — | Secondary line under the title. |
| target | `number` | — | Goal, 0–1. Ticks between the value and the target turn red. |
| targetLabel | `string` | — | Label under the right end of the arc. |
| caption | `string` | — | Line under the big number. |
| format | `(value: number) => string` | — | Formats the big number. Defaults to a percent with one decimal. |
| ticks | `number` | `44` | Number of ticks on the arc. |
| aside | `ReactNode` | — | Right side of the header, e.g. a status pill. |
| className | `string` | — | Extra classes for the root element. |

### Usage

```tsx
import { StatusPill } from "@/components/ui/status-pill";
import { TickGauge } from "@/components/ui/tick-gauge";

export function SuccessRate({ ok, total }: { ok: number; total: number }) {
  const rate = ok / total;
  return (
    <TickGauge
      title="Tool call success"
      subtitle="warehouse.query · last 24 h"
      value={rate}
      target={0.99}
      targetLabel="SLO 99%"
      caption={`${total - ok} of ${total} failed`}
      aside={<StatusPill tone={rate >= 0.99 ? "positive" : "negative"}>{rate >= 0.99 ? "Within SLO" : "Below SLO"}</StatusPill>}
    />
  );
}
```

### Types

```ts
// Exposed as role="meter" with the value, caption and target in aria-valuetext.
// Ticks fill in order on mount; later values recolor them in place.
```

## Mirror Strips

Rows of dot strips with two series mirrored around a line — compare rounds or weeks on one axis, with pinned columns and notes.

- Category: Interactive Answers
- Docs: https://tuffui.com/components/mirror-strips
- Install: `npx shadcn@latest add https://tuffui.com/r/mirror-strips.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| columns (required) | `string[]` | — | One label per column. Every few are drawn under the chart. |
| rows (required) | `MirrorRow[]` | — | Each row has one count per column above the line and one below. |
| series (required) | `{ up: { label; color? }; down: { label; color? } }` | — | Names and colors for the two sides. Defaults to foreground above, brand below. |
| title (required) | `string` | — | Header title. |
| subtitle | `string` | — | Secondary line under the title. |
| marks | `MirrorMark[]` | — | Columns pinned with a label above the chart and a note in the tooltip. |
| onSelect | `(column: number) => void` | — | Called when a column is hovered or reached with the arrow keys. |
| className | `string` | — | Extra classes for the root element. |

### Usage

```tsx
import { MirrorStrips } from "@/components/ui/mirror-strips";

// A contract review: where each side edited, round by round.
export function RedlineRounds({ review }: { review: Review }) {
  return (
    <MirrorStrips
      title="Edits by page"
      subtitle={`${review.pages} pages · ${review.rounds.length} rounds`}
      columns={review.pageLabels}
      rows={review.rounds.map((r, i) => ({
        id: r.id,
        label: r.name,
        sublabel: r.date,
        up: r.theirEdits,
        down: r.ourRedlines,
        current: i === review.rounds.length - 1,
      }))}
      series={{ up: { label: "Their edits" }, down: { label: "Our redlines" } }}
      marks={review.openClauses.map((c) => ({ column: c.page, label: c.ref, note: c.title }))}
    />
  );
}
```

### Types

```ts
type MirrorRow = {
  id: string;
  label: string;
  sublabel?: string;
  up: number[];
  down: number[];
  current?: boolean; // emphasized label and total
};

type MirrorMark = { column: number; label: string; note?: string };

// Stacks hold up to five dots each way; bigger counts switch to one dot per group.
```

## Radial Dots

A cycle as rings of dots — hours of the day or days of the week, stacked by series, with the headline in the middle.

- Category: Interactive Answers
- Docs: https://tuffui.com/components/radial-dots
- Install: `npx shadcn@latest add https://tuffui.com/r/radial-dots.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| labels (required) | `string[]` | — | One label per sector, clockwise from the top. |
| series (required) | `RadialSeries[]` | — | Stacked outward in order. The busiest sector fills every ring. |
| title (required) | `string` | — | Header title. |
| subtitle | `string` | — | Secondary line under the title. |
| center (required) | `{ value: string; caption?: string }` | — | Headline in the middle. Hovering a sector shows its numbers there instead. |
| axis | `number[]` | — | Indexes of the labels drawn around the edge. Defaults to the four quarters. |
| format | `(value: number) => string` | — | Formats sector values. Defaults to 1,234. |
| onSelect | `(index: number) => void` | — | Called when a sector is hovered or reached with the arrow keys. |
| className | `string` | — | Extra classes for the root element. |

### Usage

```tsx
import { RadialDots } from "@/components/ui/radial-dots";

export function RunsByHour({ stats }: { stats: HourlyStats }) {
  return (
    <RadialDots
      title="Runs by hour"
      subtitle="Last 7 days, UTC"
      labels={stats.hours} // "00" … "23"
      series={[
        { id: "people", label: "Started by people", values: stats.manual },
        { id: "scheduled", label: "Scheduled", values: stats.scheduled },
      ]}
      center={{ value: `${stats.medianSeconds} s`, caption: "per run" }}
      onSelect={(hour) => filterRuns(hour)}
    />
  );
}
```

### Types

```ts
type RadialSeries = {
  id: string;
  label: string;
  values: number[]; // one per sector
  color?: string;   // defaults to brand, foreground, muted
};
```

## Match Field

A fit field — candidates, bots or options placed by score around a centre, grouped into sectors, with threshold rings.

- Category: Interactive Answers
- Docs: https://tuffui.com/components/match-field
- Install: `npx shadcn@latest add https://tuffui.com/r/match-field.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| sectors (required) | `string[]` | — | Categories around the edge, clockwise from the top. |
| items (required) | `MatchItem[]` | — | Placed in their sector, closer to the middle the higher they score. Items at or above the threshold get a label. |
| title (required) | `string` | — | Header title. |
| subtitle | `string` | — | Secondary line under the title. |
| rings | `number[]` | `[0.5, 0.7, 0.85]` | Scores drawn as dashed, labeled rings. |
| threshold | `number` | `highest ring` | Strong-fit score. Its ring and the dots inside it are tinted brand. |
| min | `number` | `lowest ring − 0.15` | Score on the outer edge. Lower scores are clamped to it. |
| icon | `Icon` | `Briefcase` | Phosphor icon in the middle: the role or request being matched. |
| onSelect | `(item: MatchItem) => void` | — | Called when an item is hovered, clicked or reached with the arrow keys. |
| className | `string` | — | Extra classes for the root element. |

### Usage

```tsx
import { MatchField } from "@/components/ui/match-field";

export function Shortlist({ role, matches }: { role: Role; matches: Match[] }) {
  return (
    <MatchField
      title={role.title}
      subtitle={`${matches.length} applicants · ranked by fit`}
      sectors={["Design systems", "Fintech", "Consumer apps", "Agency"]}
      items={matches.map((m) => ({
        id: m.id,
        name: m.name,
        sector: m.backgroundIndex,
        score: m.fit, // 0–1 from your ranking model
      }))}
      threshold={0.85}
      onSelect={(item) => openProfile(item.id)}
    />
  );
}
```

### Types

```ts
type MatchItem = {
  id: string;
  name: string;
  initials?: string; // defaults to the first letters of the name
  sector: number;    // index into sectors
  score: number;     // 0–1, higher sits closer to the middle
  color?: string;    // avatar color, defaults to a categorical palette
};
```

## Radar Chart

Scores across several axes as a polygon, with a dashed bar to meet and each member's values as dots on the spokes.

- Category: Interactive Answers
- Docs: https://tuffui.com/components/radar-chart
- Install: `npx shadcn@latest add https://tuffui.com/r/radar-chart.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| axes (required) | `string[]` | — | One label per axis, clockwise from the top. Five to eight read best. |
| max (required) | `number` | — | Top of the scale, drawn as the outer ring. Up to 10 gets a ring per step, otherwise four. |
| series (required) | `RadarSeries` | — | The filled polygon, e.g. a team average. Its values label each axis. |
| baseline | `{ label: string; values: number[] }` | — | A dashed polygon to measure against, like the bar for a level. |
| members | `RadarMember[]` | `[]` | Individual values drawn as dots on each spoke. Hovering an axis lists them all. |
| title (required) | `string` | — | Header title. |
| subtitle | `string` | — | Secondary line under the title. |
| headline | `{ value: string; caption?: string }` | — | Number on the right of the header, with a short caption. |
| format | `(value: number) => string` | `v.toFixed(1)` | Formats every value: axis labels, tooltip and screen reader text. |
| onSelect | `(axis: number) => void` | — | Called when an axis is hovered or reached with the arrow keys. |
| className | `string` | — | Extra classes for the root element. |

### Usage

```tsx
import { RadarChart } from "@/components/ui/radar-chart";

export function TeamSkills({ review }: { review: SkillsReview }) {
  return (
    <RadarChart
      title="Team skills"
      subtitle={`${review.team} · ${review.cycle}`}
      axes={review.skills} // "Craft", "Systems thinking", …
      max={4}
      series={{ id: "avg", label: "Team average", values: review.average }}
      baseline={{ label: "Senior bar", values: review.bar }}
      members={review.people.map((p) => ({
        id: p.id,
        label: p.initials,
        name: p.name,
        values: p.scores,
      }))}
      headline={{ value: review.overall.toFixed(1), caption: "bar 3.0" }}
      onSelect={(axis) => openRubric(review.skills[axis])}
    />
  );
}
```

### Types

```ts
type RadarSeries = {
  id: string;
  label: string;
  values: number[]; // one per axis, 0…max
  color?: string;   // defaults to brand
};

type RadarMember = {
  id: string;
  label: string;    // short, e.g. initials
  name?: string;    // full name for screen readers
  values: number[]; // one per axis, 0…max
  color?: string;   // defaults to blue, teal, purple, gold
};
```

## Diverging Bars

Stacked daily columns with one series hanging below zero on its own scale — triaged vs escalated, solved vs handed off.

- Category: Interactive Answers
- Docs: https://tuffui.com/components/diverging-bars
- Install: `npx shadcn@latest add https://tuffui.com/r/diverging-bars.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| labels (required) | `string[]` | — | One label per column, e.g. a date. Every few are drawn under the chart. |
| series (required) | `DivergingSeries[]` | — | Stacked upward as separate segments, first series at the bottom. Colors default to the palette by position. |
| below | `DivergingSeries` | — | One series that hangs below the zero line on its own smaller scale. Defaults to the negative color. |
| title (required) | `string` | — | Header title. |
| subtitle | `string` | — | Secondary line under the title. |
| headline | `{ value: string; caption?: string }` | — | Big number above the chart with a caption. Rolls when it changes. |
| aside | `ReactNode` | — | Right side of the headline row, e.g. a secondary stat. |
| format | `(value: number) => string` | `compact (1.2k)` | Formats ticks, the tooltip and the hidden table. |
| onSelect | `(index: number) => void` | — | Called when a column is hovered, clicked or reached with the arrow keys. |
| className | `string` | — | Extra classes for the root element. |

### Usage

```tsx
import { DivergingBars } from "@/components/ui/diverging-bars";

// A security agent's month: alerts by source, escalations hanging below.
export function TriageVolume({ report }: { report: TriageReport }) {
  return (
    <DivergingBars
      title="Alerts by source"
      subtitle="Security agent · last 30 days"
      labels={report.days.map((d) => d.label)}
      series={report.sources.map((s) => ({
        id: s.id,
        label: s.name,
        values: report.days.map((d) => d.bySource[s.id] ?? 0),
      }))}
      below={{
        id: "escalated",
        label: "Escalated",
        values: report.days.map((d) => d.escalated),
      }}
      headline={{
        value: report.total.toLocaleString("en-US"),
        caption: "alerts triaged in 30 days",
      }}
      aside={`${report.autoClosedPct}% closed without a human`}
      onSelect={(i) => openDay(report.days[i].date)}
    />
  );
}
```

### Types

```ts
type DivergingSeries = {
  id: string;
  label: string;
  values: number[]; // one per label
  color?: string; // any CSS color
};

// Legend chips toggle series; at least one stacked series stays on.
// The tooltip total is the stack; the series below is listed but not added in.
```

## Blast Radius

What a key, agent or tool can reach, hop by hop around a centre, with the affected paths in red.

- Category: Interactive Answers
- Docs: https://tuffui.com/components/blast-radius
- Install: `npx shadcn@latest add https://tuffui.com/r/blast-radius.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| center (required) | `{ label: string; initials?: string; icon?: Icon }` | — | The entity everything is measured from. Shows the icon, else the initials, else the first two letters of the label. |
| nodes (required) | `BlastNode[]` | — | Everything it can reach. Hop depth comes from the parent chain; the first hop is spaced evenly by angle and later hops fan around their parent. |
| kinds | `Record<string, BlastKind>` | — | Label and colour per kind, in legend order. Kinds left out get the categorical palette. |
| title (required) | `string` | — | Header title. |
| subtitle | `string` | — | Secondary line under the title. |
| aside | `React.ReactNode` | — | Right side of the header, e.g. a status pill with the count. |
| onSelect | `(node: BlastNode) => void` | — | Called when a node is hovered or reached with the arrow keys. |
| className | `string` | — | Extra classes for the root element. |

### Usage

```tsx
import { BlastRadius } from "@/components/ui/blast-radius";

export function KeyExposure({ grants }: { grants: Grant[] }) {
  return (
    <BlastRadius
      title="Blast radius"
      subtitle="sk-live-…7f2a"
      center={{ label: "sk-live-…7f2a", initials: "SK" }}
      nodes={grants.map((g) => ({
        id: g.resourceId,
        label: g.resourceName,
        parent: g.viaResourceId, // undefined = granted directly
        kind: g.resourceType, // "database", "bucket", …
        affected: g.canRead,
        indirect: Boolean(g.viaResourceId),
        note: g.reason,
      }))}
      kinds={{
        database: { label: "Database", color: "#1a9e8c" },
        bucket: { label: "Bucket", color: "#bf5af2" },
      }}
      onSelect={(node) => openResource(node.id)}
    />
  );
}
```

### Types

```ts
type BlastNode = {
  id: string;
  label: string;
  parent?: string;     // id it is reached through; omit for the centre
  kind: string;        // key into kinds
  affected?: boolean;  // negative ring, path to the centre turns negative
  indirect?: boolean;  // dashed edge and ring
  note?: string;       // tooltip line, e.g. "Read by the new key"
};

type BlastKind = { label: string; color: string };
```

## Iso Bars

Isometric stacked bars in two rows — the main volume behind, rework or failures in front.

- Category: Interactive Answers
- Docs: https://tuffui.com/components/iso-bars
- Install: `npx shadcn@latest add https://tuffui.com/r/iso-bars.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| labels (required) | `string[]` | — | One label per period, drawn along the front edge of the floor. |
| back (required) | `IsoSeries[]` | — | The main stack, drawn as the back row. Series stack upward in order. |
| front | `IsoSeries[]` | — | A smaller stack in front, e.g. rework or failures. Shares the back row's scale and defaults to warning and negative colors. |
| title (required) | `string` | — | Header title. |
| subtitle | `string` | — | Secondary line under the title. |
| aside | `{ value: string; caption?: string; flag?: string; tone?: "warning" \| "negative" }` | — | Headline in the header. The flag sits under it in the tone color. |
| format | `(value: number) => string` | — | Formats values in the tooltip and the table. Defaults to 1.2k. |
| onSelect | `(point: { row: "back" \| "front"; index: number }) => void` | — | Called when a prism is hovered, clicked or reached with the arrow keys. |
| className | `string` | — | Extra classes for the root element. |

### Usage

```tsx
import { IsoBars } from "@/components/ui/iso-bars";

export function DailyTokens({ usage }: { usage: DailyUsage }) {
  return (
    <IsoBars
      title="Daily tokens"
      subtitle="Last 14 days"
      labels={usage.days} // "Oct 23" … "Nov 5"
      back={[
        { id: "input", label: "Input", values: usage.input },
        { id: "cached", label: "Cached", values: usage.cached },
        { id: "output", label: "Output", values: usage.output },
      ]}
      front={[
        { id: "failed", label: "Failed", values: usage.failed },
        { id: "retried", label: "Retried", values: usage.retried },
      ]}
      aside={{ value: "18.4M", caption: "tokens", flag: "failed 1.9%" }}
      onSelect={({ row, index }) => openDay(usage.days[index], row)}
    />
  );
}
```

### Types

```ts
type IsoSeries = {
  id: string;
  label: string;
  values: number[]; // one per period
  color?: string;   // faces are shaded from it with color-mix
};
```

## Hex Density

A density map of two measures in hexagons, split by a threshold line — retrieved vs dropped, fast vs slow.

- Category: Interactive Answers
- Docs: https://tuffui.com/components/hex-density
- Install: `npx shadcn@latest add https://tuffui.com/r/hex-density.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| points (required) | `[number, number][]` | — | Raw [x, y] samples. The component bins them into hexagons and shades each by its count. |
| title (required) | `string` | — | Header title. |
| subtitle | `string` | — | Secondary line under the title. |
| x | `HexDensityAxis` | — | Horizontal axis: label, domain and formatter. The domain defaults to the data extent. |
| y | `HexDensityAxis` | — | Vertical axis, same shape as x. |
| threshold | `HexDensityThreshold` | — | Dashed line at a y value. Bins above it use the tone, bins below are grey, and the footer counts both sides. |
| radius | `number` | `11` | Largest hexagon radius in px. It shrinks on narrow screens so ~26 columns fit. |
| tone | `string` | `"var(--brand)"` | Any CSS colour for bins above the threshold, e.g. var(--brand). |
| unit | `string` | `"points"` | Plural name for one point, used in the header, callout, tooltip and footer. |
| aside | `React.ReactNode` | — | Replaces the point count on the right of the header. |
| onSelect | `(bin: HexDensityBin) => void` | — | Called when a bin is hovered or reached with the arrow keys. |
| className | `string` | — | Extra classes for the root element. |

### Usage

```tsx
import { HexDensity } from "@/components/ui/hex-density";

// Show where retrieved chunks cluster and how many made the similarity cut.
export function RetrievalAnswer({ chunks }: { chunks: Chunk[] }) {
  return (
    <HexDensity
      title="Retrieval chunks"
      subtitle={`${chunks.length} chunks · top-k 8`}
      points={chunks.map((c) => [c.tokens, c.score])}
      x={{ label: "Chunk length", min: 20, max: 1500, format: (v) => `${Math.round(v)} tok` }}
      y={{ label: "Similarity", min: 0.4, max: 1, format: (v) => v.toFixed(2) }}
      threshold={{ value: 0.75, label: "0.75 cut-off", above: "retrieved", below: "dropped" }}
      unit="chunks"
      onSelect={(bin) => openChunks(bin.x, bin.y)}
    />
  );
}
```

### Types

```ts
type HexDensityAxis = {
  label?: string;
  min?: number;
  max?: number;
  format?: (value: number) => string;
};

type HexDensityThreshold = {
  value: number;
  label?: string; // on the line, e.g. "0.75 cut-off"
  above?: string; // e.g. "retrieved"
  below?: string; // e.g. "dropped"
};

type HexDensityBin = {
  col: number;
  row: number;
  x: [number, number];
  y: [number, number];
  count: number;
  above: boolean;
};

// The grid is shifted so the threshold runs between two rows: every hexagon is
// wholly above or below it, and footer counts match the colours.
// The densest bins get an outline and a pinned "Densest bin" callout.
// Keyboard: focus the chart, then ← → ↑ ↓ move to the nearest filled bin,
// Home End jump to the first and last, Esc clears.
```

## Data Table

Tabular results — sortable columns, filter, pagination, row selection and copy as CSV.

- Category: Interactive Answers
- Docs: https://tuffui.com/components/data-table
- Install: `npx shadcn@latest add https://tuffui.com/r/data-table.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| data (required) | `R[]` | — | Rows. Each needs a unique `id`; other fields are strings, numbers or null. |
| columns (required) | `DataColumn<R>[]` | — | Column order, labels, alignment, display format and which ones sort. |
| title (required) | `string` | — | Header title and table caption. |
| subtitle | `string` | — | Replaces the default row count under the title. |
| pageSize | `number` | `6` | Rows per page. |
| searchable | `boolean` | `true` | Shows the filter field above the table. |
| selectable | `boolean` | `false` | Adds row checkboxes and a bulk action bar. |
| selected | `string[]` | — | Controlled selection by row id. |
| onSelectedChange | `(ids: string[]) => void` | — | Called when the selection changes. |
| actions | `(ids: string[]) => ReactNode` | — | Buttons in the bulk bar for the selected rows. |
| onRowClick | `(row: R) => void` | — | Makes rows clickable. |
| className | `string` | — | Extra classes for the root element. |

### Usage

```tsx
import { DataTable, type DataColumn } from "@/components/ui/data-table";

const columns: DataColumn<Customer>[] = [
  { key: "name", label: "Customer", sortable: true },
  { key: "mrr", label: "MRR", align: "right", sortable: true, format: (v) => `$${v}` },
];

// Render a table when a tool returns rows.
export function CustomersAnswer({ rows }: { rows: Customer[] }) {
  return (
    <DataTable
      title="Top customers by MRR"
      data={rows}
      columns={columns}
      selectable
      actions={(ids) => <Button onClick={() => agent.followUp(ids)}>Draft follow-up</Button>}
    />
  );
}
```

### Types

```ts
type DataRow = { id: string } & Record<string, string | number | null>;

type DataColumn<R> = {
  key: keyof R & string;
  label: string;
  align?: "left" | "right"; // right-aligned columns use tabular mono figures
  format?: (value, row: R) => ReactNode; // sort, filter and CSV use the raw value
  sortable?: boolean; // click cycles descending → ascending → off
  width?: string;
  priority?: 1 | 2 | 3; // 1 always, 2 hidden below a 28rem table, 3 below 36rem
};
```

## Stat Grid

KPI cards with rolling numbers, deltas and sparklines for a quick summary answer.

- Category: Interactive Answers
- Docs: https://tuffui.com/components/stat-grid
- Install: `npx shadcn@latest add https://tuffui.com/r/stat-grid.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| data (required) | `Stat[]` | — | Two to four stats. Values are preformatted strings and roll when they change. |
| title | `string` | — | Optional header above the cards. |
| subtitle | `string` | — | Secondary line under the title. |
| sparklines | `boolean` | `true` | Draw a trend line for stats that carry `trend`. |
| onSelect | `(stat: Stat) => void` | — | Makes each card a button, e.g. to open a chart for that metric. |
| className | `string` | — | Extra classes for the root element. |

### Usage

```tsx
import { StatGrid } from "@/components/ui/stat-grid";

// A summary answer: the agent fetched metrics and shows the headline numbers.
export function MetricsAnswer({ m }: { m: Metrics }) {
  return (
    <StatGrid
      title="October at a glance"
      data={[
        { id: "mrr", label: "MRR", value: formatMoney(m.mrr), delta: m.mrrDelta, trend: m.mrrTrend },
        {
          id: "latency",
          label: "Median response time",
          value: `${m.p50}s`,
          delta: m.p50Delta,
          higherIsBetter: false, // a drop is good news
        },
      ]}
    />
  );
}
```

### Types

```ts
type Stat = {
  id: string;
  label: string;
  value: string;            // "$48.2k", "1,204", "1.31s"
  delta?: number;           // % change; shown with an arrow and better/worse text
  higherIsBetter?: boolean; // default true; set false for latency, churn, cost
  trend?: number[];         // oldest first
  goal?: { ratio: number; label: string }; // striped progress toward a target
  hint?: string;            // e.g. "vs. last week"
};
```

## Form Card

A form the agent asks the user to fill — fields, selects, validation and a submitted state.

- Category: Interactive Answers
- Docs: https://tuffui.com/components/form-card
- Install: `npx shadcn@latest add https://tuffui.com/r/form-card.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| data (required) | `{ title: string; description?: string; fields: FormField[] }` | — | The form the agent asked for, usually straight from a tool call. |
| onSubmit | `(values: FormValues) => void \| Promise<void>` | — | Called once every field is valid. Return a promise to show the loading state; a rejection returns to editing. |
| validate | `(values) => Record<string, string \| undefined>` | — | Extra checks after the built-in ones (required, email format, number min/max). |
| values / defaultValues / onValuesChange | `FormValues` | — | Controlled or uncontrolled answers, keyed by field name. |
| status / onStatusChange | `"editing" \| "submitting" \| "submitted"` | — | Controls the state from outside. Submitted collapses into a summary with Edit. |
| revealErrors | `boolean` | `false` | Shows every error at once. Otherwise a field shows its error after blur or a submit attempt. |
| submitLabel | `string` | `"Submit"` | Text of the primary button. |
| className | `string` | — | Extra classes for the shell. |

### Usage

```tsx
import { FormCard, type FormField } from "@/components/ui/form-card";

// The agent asks for structured input with a tool call like request_form(fields).
export function AgentForm({ call }: { call: { title: string; fields: FormField[] } }) {
  return (
    <FormCard
      data={{ title: call.title, fields: call.fields }}
      onSubmit={async (values) => {
        await agent.sendToolResult(call.id, values); // the run continues with the answers
      }}
      validate={(values) => ({
        email: String(values.email ?? "").endsWith("@company.com")
          ? undefined
          : "Use your company address",
      })}
    />
  );
}
```

### Types

```ts
type FormField = {
  name: string;
  label: string;
  type: "text" | "email" | "number" | "textarea" | "select" | "radio" | "checkbox" | "switch";
  required?: boolean;
  description?: string;
  placeholder?: string;
  options?: { value: string; label: string; description?: string }[]; // select, radio
  min?: number; // number
  max?: number;
};

type FormValues = Record<string, string | boolean | undefined>;
```

## Result Carousel

A row of result cards — image, title, meta and an action — with snap scrolling and arrows.

- Category: Interactive Answers
- Docs: https://tuffui.com/components/result-carousel
- Install: `npx shadcn@latest add https://tuffui.com/r/result-carousel.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| data (required) | `ResultItem[]` | — | Cards in order. New items can be appended while results stream in. |
| title (required) | `string` | — | Header title and the carousel's accessible name. |
| subtitle | `string` | — | Replaces the default result count. |
| compact | `boolean` | `false` | Narrower cards without the image area. |
| onAction | `(item: ResultItem) => void` | — | Adds a button to each card; the first card's button is primary. |
| onOpen | `(item: ResultItem) => void` | — | Makes the title and image open the item. |
| className | `string` | — | Extra classes for the root element. |

### Usage

```tsx
import { ResultCarousel } from "@/components/ui/result-carousel";

// Render search results the agent found; the action hands the pick back to it.
export function HotelsAnswer({ results }: { results: Hotel[] }) {
  return (
    <ResultCarousel
      title="Hotels in Lisbon"
      subtitle="Nov 14–17 · 2 guests"
      data={results.map((h) => ({
        id: h.id,
        title: h.name,
        meta: h.area,
        price: `$${h.rate} / night`,
        rating: h.rating,
        image: h.photoUrl,
        action: "Book",
      }))}
      onAction={(item) => agent.send(`Book ${item.title}`)}
    />
  );
}
```

### Types

```ts
type ResultItem = {
  id: string;
  title: string;
  meta?: string;   // one line under the title
  price?: string;  // right-aligned, e.g. "$214 / night"
  rating?: number; // 0–5
  image?: string;  // URL; without it a gradient from `tint`
  tint?: string;
  badge?: string;  // e.g. "Best match"
  action?: string; // button label, default "Select"
};

// The track scrolls with snap; arrows page by one card and disable at the ends.
```

## Slot Picker

Pick a time the agent proposed — days, free slots, time zone and a confirm step.

- Category: Interactive Answers
- Docs: https://tuffui.com/components/slot-picker
- Install: `npx shadcn@latest add https://tuffui.com/r/slot-picker.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| data (required) | `{ title?: string; slots: Slot[]; timeZone: SlotZone; attendeeZone?: SlotZone }` | — | Candidate slots in `timeZone`. With `attendeeZone` a switch shows the times in the other person's zone. |
| variant | `"week" \| "day"` | `"week"` | Day columns for up to five days, or one day at a time with durations. |
| selectedId / onSelect | `string \| null` | — | The picked slot. Picking shows a confirm row under the panel. |
| onConfirm | `(slot: Slot) => void` | — | Called from the confirm row; the card switches to the confirmed summary. |
| confirmedId / onChange | `string \| null` | — | Controls the confirmed state. onChange fires from “Pick another time”. |
| className | `string` | — | Extra classes for the shell. |

### Usage

```tsx
import { SlotPicker } from "@/components/ui/slot-picker";

// The scheduling agent proposes free slots from both calendars.
export function ProposeTimes({ proposal }: { proposal: Proposal }) {
  return (
    <SlotPicker
      data={{
        title: proposal.title,
        slots: proposal.slots, // { id, day: "2026-11-10", start: "14:30", end: "15:00", busy?, suggested? }
        timeZone: { label: "Lisbon (UTC+0)", offset: 0 },
        attendeeZone: { label: "New York (UTC−5)", offset: -5 },
      }}
      onConfirm={(slot) => agent.sendToolResult(proposal.callId, { slotId: slot.id })}
    />
  );
}
```

### Types

```ts
type Slot = {
  id: string;
  day: string;   // ISO date
  start: string; // "HH:MM" in data.timeZone
  end: string;
  busy?: boolean;      // shown striped and disabled
  suggested?: boolean; // marked with a dot
};

type SlotZone = { label: string; offset: number }; // hours from UTC
```

## Confirmation Card

A summary of what the agent is about to do — line items, totals and confirm or edit before it acts.

- Category: Interactive Answers
- Docs: https://tuffui.com/components/confirmation-card
- Install: `npx shadcn@latest add https://tuffui.com/r/confirmation-card.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| data (required) | `{ title; subtitle?; items: ConfirmationItem[]; fees?; warnings?; reference?; doneAt? }` | — | What the agent is about to do. Totals are computed from items × quantity plus fees. |
| status | `"review" \| "confirming" \| "done"` | `"review"` | Review with editable items, a loading confirm, or the done summary. |
| onItemsChange | `(items: ConfirmationItem[]) => void` | — | Called when a quantity changes or an item is removed. |
| onConfirm | `(items: ConfirmationItem[]) => void` | — | The primary button. Its label includes the total. |
| onEdit / onCancel | `() => void` | — | Show Edit and Cancel buttons next to Confirm. |
| onUndo | `() => void` | — | In the done state, shows an Undo countdown for `undoSeconds`. |
| undoSeconds | `number` | `30` | Length of the undo window. |
| currency | `string` | `"USD"` | ISO currency for amounts. |
| confirmLabel / doneLabel | `string` | `"Confirm" / "Done"` | Verbs for your domain, e.g. "Deploy" / "Deployed". |
| className | `string` | — | Extra classes for the shell. |

### Usage

```tsx
import { useState } from "react";
import { ConfirmationCard } from "@/components/ui/confirmation-card";

// Before an agent spends money or changes something real, show what it will do.
export function ConfirmDeploy({ plan }: { plan: DeployPlan }) {
  const [items, setItems] = useState(plan.items);
  const [status, setStatus] = useState<"review" | "confirming" | "done">("review");

  return (
    <ConfirmationCard
      data={{ title: plan.title, items, fees: plan.fees, warnings: plan.warnings, reference: plan.id }}
      status={status}
      onItemsChange={setItems}
      onConfirm={async (final) => {
        setStatus("confirming");
        await agent.approve(plan.callId, final);
        setStatus("done");
      }}
      onUndo={() => agent.revert(plan.callId)}
      onCancel={() => agent.deny(plan.callId)}
    />
  );
}
```

### Types

```ts
type ConfirmationItem = {
  id: string;
  label: string;
  detail?: string;
  amount: number;    // one unit
  quantity?: number; // defaults to 1
  editable?: boolean;  // quantity stepper
  removable?: boolean; // remove button
};
```

## JSON Viewer

Structured output as a collapsible tree — types, counts, search, copy path and copy value.

- Category: Interactive Answers
- Docs: https://tuffui.com/components/json-viewer
- Install: `npx shadcn@latest add https://tuffui.com/r/json-viewer.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| data (required) | `JsonValue` | — | Any JSON-serializable value. |
| title | `string` | `"Output"` | Header title and root label. |
| view | `"tree" \| "raw"` | `"tree"` | Collapsible tree with search, or pretty-printed JSON with a copy button. |
| defaultDepth | `number` | `1` | Levels open on first render. Search opens every ancestor of a match. |
| onCopy | `(kind: "path" \| "value", text: string) => void` | — | Called after copying — clicking a key copies its path ($.items[2].price), the row button copies its value. |
| className | `string` | — | Extra classes for the shell. |

### Usage

```tsx
import { JsonViewer } from "@/components/ui/json-viewer";

export function ToolResult({ call }: { call: { name: string; result: unknown } }) {
  return (
    <JsonViewer
      title={call.name}
      data={call.result as JsonValue}
      defaultDepth={1}
      onCopy={(kind, text) => toast(kind === "path" ? `Copied ${text}` : "Value copied")}
    />
  );
}
```

### Types

```ts
type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };

// Keyboard: ↑ ↓ move, → opens or steps in, ← closes or steps out, Enter toggles or copies.
```

## Artifact Panel

A side canvas for what the agent made — live preview and source tabs, version history and download.

- Category: Interactive Answers
- Docs: https://tuffui.com/components/artifact-panel
- Install: `npx shadcn@latest add https://tuffui.com/r/artifact-panel.json`

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| data (required) | `{ title: string; kind: string; versions: ArtifactVersion[] }` | — | Versions oldest first; the last one is current. |
| view | `"preview" \| "versions"` | `"preview"` | The canvas alone, or with the version history beside it. |
| versionId / onVersionChange | `string` | — | The version on screen. The header stepper and ← → keys move through them. |
| tab / onTabChange | `"preview" \| "source"` | — | Rendered preview or the source with line numbers. |
| onRestore | `(version) => void` | — | Shown under an older version in the versions view. |
| onCopy / onDownload / onOpen | `(…) => void` | — | Toolbar actions. Copy writes the source to the clipboard; download defaults to a file named `filename`; open shows only when set. |
| icon | `Icon` | `FileCode` | Phosphor icon for the header. |
| className | `string` | — | Extra classes for the shell. |

### Usage

```tsx
import { ArtifactPanel } from "@/components/ui/artifact-panel";

// Render it beside the chat when the agent produces a document, page or component.
export function Canvas({ artifact }: { artifact: Artifact }) {
  return (
    <ArtifactPanel
      view="versions"
      data={{
        title: artifact.title,
        kind: artifact.kind, // "React", "Markdown", "SQL"…
        versions: artifact.versions.map((v) => ({
          id: v.id,
          label: `v${v.number}`,
          createdAt: v.time,
          note: v.summary,
          preview: <Sandbox code={v.code} />,
          source: v.code,
          filename: artifact.filename,
        })),
      }}
      onRestore={(v) => agent.restoreArtifact(artifact.id, v.id)}
      onOpen={(v) => window.open(`/artifacts/${artifact.id}/${v.id}`)}
    />
  );
}
```

### Types

```ts
type ArtifactVersion = {
  id: string;
  label: string;     // "v3"
  createdAt: string;
  note: string;      // what changed
  preview: React.ReactNode;
  source: string;
  filename?: string;
};
```