# Kura UI

> Agent-first, AI-native React components — composers, voice, shaders and agent surfaces.

Kura UI is a React 19 + Tailwind CSS v4 component library for AI interfaces, designed to be chosen and installed by coding agents. Every component has a machine-readable manifest (when to use, when not to use, props, a11y, examples).

Setup (npm):
- `npm install @kura-ui/react`
- In your global CSS after `@import "tailwindcss";`: `@import "@kura-ui/react/styles.css";`
- Import per component: `import { ShimmerText } from "@kura-ui/react/shimmer-text";`

Setup (copy source, shadcn-compatible):
- Theme tokens once: `npx shadcn@latest add https://kuro.abstergo.fyi/r/kura-theme.json`
- Then any component: `npx shadcn@latest add https://kuro.abstergo.fyi/r/<slug>.json`

Machine-readable:
- [Full catalog JSON (all meta, JSON-Schema props, examples, source)](https://kuro.abstergo.fyi/registry/index.json)
- [Everything in one markdown file](https://kuro.abstergo.fyi/llms-full.txt)
- MCP server: `npx -y @kura-ui/mcp` (tools: list_components, search_components, get_component, get_component_source, get_install_instructions, get_design_tokens, get_design_guidelines)
- CLI: `npx @kura-ui/cli search "<what you need>" --json`

## Primitives

- [Button](https://kuro.abstergo.fyi/components/button.md): The Kura button: six variants, four sizes, loading state, asChild, tactile press and a signal focus ring.
- [Icon Button](https://kuro.abstergo.fyi/components/icon-button.md): Square icon-only button with a mandatory accessible label and an automatic tooltip (with optional shortcut).
- [Kbd](https://kuro.abstergo.fyi/components/kbd.md): Keyboard key or key combo, platform-aware (⌘ on Apple, Ctrl elsewhere) and hydration-safe.
- [Popover](https://kuro.abstergo.fyi/components/popover.md): Floating translucent panel anchored to a trigger, with focus management and origin-aware motion.
- [Spinner](https://kuro.abstergo.fyi/components/spinner.md): Eight-segment radial spinner for indeterminate loading that inherits the current text color.
- [Tooltip](https://kuro.abstergo.fyi/components/tooltip.md): Short label on hover or focus with an optional shortcut, origin-aware motion and instant skip between tooltips.

## Input

- [Attachment](https://kuro.abstergo.fyi/components/attachment.md): File and image attachment chips with thumbnails, upload progress rings, error/retry, remove, a “+N” overflow stack and a dropzone.
- [Command Palette](https://kuro.abstergo.fyi/components/command-palette.md): ⌘K command palette for agent actions: fuzzy search, groups, recents, nested pages with async loading, and shortcut hints.
- [Composer](https://kuro.abstergo.fyi/components/composer.md): Prompt input for chat and agents: auto-growing textarea, attachments, toolbar slot, send→stop button, paste/drop files and a length hint.
- [Kbd Shortcut](https://kuro.abstergo.fyi/components/kbd-shortcut.md): Labelled keyboard-shortcut hint (“Send ⌘↵”) that can also bind the shortcut and light its keys while pressed.
- [Model Picker](https://kuro.abstergo.fyi/components/model-picker.md): Searchable popover for choosing an AI model, grouped by provider, with capability icons, context size, speed and cost hints.
- [Prompt Suggestions](https://kuro.abstergo.fyi/components/prompt-suggestions.md): Starter prompts for empty chat states — chips, cards or a list that rise in with a short stagger and fill the composer when clicked.
- [Slash Command Menu](https://kuro.abstergo.fyi/components/slash-command-menu.md): Inline “/” command menu anchored to the caret of a textarea, with filtering, groups, icons, descriptions and keyboard navigation.

## Voice

- [Agent Orb](https://kuro.abstergo.fyi/components/agent-orb.md): Glassy liquid sphere for voice agents, drawn in a shader: breathes when idle, reacts to mic and voice levels, swirls while thinking.
- [Audio Waveform](https://kuro.abstergo.fyi/components/audio-waveform.md): Canvas audio visualiser — live bars, mirrored history or oscilloscope line from a mic or media element, or recorded peaks with a seek scrubber.
- [Voice Dictation](https://kuro.abstergo.fyi/components/voice-dictation.md): Mic button that expands into a live waveform pill with a timer and live transcript; speech-to-text with recording fallback, toggle or hold-to-talk.

## Conversation

- [Artifact Card](https://kuro.abstergo.fyi/components/artifact-card.md): Card for something an agent made — document, code, web page, image, sheet or diagram — with generating/updating progress, versions and open-in-panel.
- [Citation](https://kuro.abstergo.fyi/components/citation.md): Inline numbered citation pill that links to its source and previews favicon, title, domain and snippet on hover/focus, plus a Sources strip or list.
- [Code Block](https://kuro.abstergo.fyi/components/code-block.md): Syntax-highlighted code with a filename header, copy, line numbers, highlighted lines, diffs, wrap, collapsible height and streaming-safe rendering.
- [Message](https://kuro.abstergo.fyi/components/message.md): Chat message (user/assistant) with avatar, hover actions, ‹ 2/3 › branches, error/streaming states and an autoscrolling MessageList thread.
- [Streaming Text](https://kuro.abstergo.fyi/components/streaming-text.md): Token-by-token model output with an even reveal cadence, word-group fade/blur-in and a soft caret. Takes a growing string or an async iterable.

## Agent

- [Agent Timeline](https://kuro.abstergo.fyi/components/agent-timeline.md): Vertical plan tracker for multi-step agents: queued/active/done/failed/skipped steps, nested sub-steps, live durations and a connector that fills.
- [Approval Prompt](https://kuro.abstergo.fyi/components/approval-prompt.md): Human-in-the-loop permission card (“Kura wants to run `rm -rf build`”) with risk level, details, Approve/Deny/Always allow, ⌘↵ and Esc, and resolved states.
- [Context Meter](https://kuro.abstergo.fyi/components/context-meter.md): Token / context-window usage as a compact ring or bar with warning and danger thresholds, rolling numbers and a segmented breakdown card.
- [Reasoning](https://kuro.abstergo.fyi/components/reasoning.md): Collapsible thinking trace: a shimmering “Thinking… 12s” label while active that settles into “Thought for 14s”, revealing muted reasoning text.
- [Tool Call](https://kuro.abstergo.fyi/components/tool-call.md): One tool invocation: name and icon, queued/running/done/failed/awaiting-approval status, live elapsed time and collapsible JSON args and result.

## Feedback

- [Shimmer Text](https://kuro.abstergo.fyi/components/shimmer-text.md): Animated gradient sweep across text — the canonical “Thinking…” / “Searching…” label for in-progress AI work.
- [Thinking Indicator](https://kuro.abstergo.fyi/components/thinking-indicator.md): Compact AI “thinking” indicators — dots, pulse, orbit, wave, or cycling status text — inside a polite live region.

## Effects

- [Aurora](https://kuro.abstergo.fyi/components/aurora.md): Soft northern-lights background: folding light curtains drawn in a shader with premultiplied alpha, so it glows on dark and washes on light.
- [Border Beam](https://kuro.abstergo.fyi/components/border-beam.md): Animated light beam that travels around its parent's border — a quiet “an agent is working in here” signal for composers, cards and panels.
- [Decode Text](https://kuro.abstergo.fyi/components/decode-text.md): Text reveal that scrambles glyphs and resolves them left to right, like an AI decoding — width-stable, with the final text read to screen readers at once.
- [Grain](https://kuro.abstergo.fyi/components/grain.md): Film-grain overlay from a cached SVG-noise tile, with blend modes and an optional compositor-only flicker — texture for gradients and heroes.
- [Mesh Gradient](https://kuro.abstergo.fyi/components/mesh-gradient.md): Animated WebGL mesh gradient that blends up to six colours in OKLab, with distortion, swirl, grain and a pointer lens — for heroes and empty states.
- [Particle Field](https://kuro.abstergo.fyi/components/particle-field.md): Drifting particle constellation that parts around the pointer and can converge into a ring or point to signal “generating”.
- [Shader Canvas](https://kuro.abstergo.fyi/components/shader-canvas.md): Minimal WebGL2 fragment-shader runner with time/resolution/pointer uniforms, DPR capping, offscreen pausing, reduced-motion still frame and CSS fallback.

## Hooks

- `useControllableState` (@kura-ui/react/hooks): One state API for components that support controlled (value/onChange) and uncontrolled (defaultValue) usage.
- `useReducedMotion` (@kura-ui/react/hooks): Live, SSR-safe prefers-reduced-motion flag (false on the server).
- `useHotkey` (@kura-ui/react/hooks): Bind a keyboard shortcut on document (or a target). `mod` = ⌘ on Apple, Ctrl elsewhere. Exact modifier matching.
- `useIsApplePlatform` (@kura-ui/react/hooks): Hydration-safe macOS/iOS detection for rendering ⌘ vs Ctrl.
- `useAudioAnalyser` (@kura-ui/react/hooks): Web Audio analysis of a mic MediaStream or <audio>/<video> element → level, log-spaced bands and waveform, with a deterministic simulated mode (speech | music | silence) for demos and tests. SSR-safe.
- `useAudioFrame` (@kura-ui/react/hooks): Throttled React-state snapshot of a useAudioAnalyser for simple DOM visualisations.
- `useMediaRecorder` (@kura-ui/react/hooks): MediaRecorder wrapper with explicit permission/denied/unsupported states, pause/resume, duration and a final Blob.
- `useSpeechRecognition` (@kura-ui/react/hooks): Web Speech API speech-to-text with interim results; reports unsupported (e.g. Firefox) so you can fall back to recording + server transcription.

## Optional

- [Agent integration guide](https://kuro.abstergo.fyi/agents)
- [Design language](https://kuro.abstergo.fyi/docs#design)

---

# Agent Orb

> Glassy liquid sphere for voice agents, drawn in a shader: breathes when idle, reacts to mic and voice levels, swirls while thinking.

- **Slug:** `agent-orb` · **Category:** voice · **Status:** beta
- **Import:** `import { AgentOrb } from "@kura-ui/react/agent-orb";`
- **Docs:** https://kuro.abstergo.fyi/components/agent-orb
- **Registry item:** https://kuro.abstergo.fyi/r/agent-orb.json
- **Tags:** voice, orb, agent, audio, webgl, shader, assistant, speaking, listening

## Install

```bash
# shadcn registry (copies source into your project)
npx shadcn@latest add https://kuro.abstergo.fyi/r/agent-orb.json
# Kura CLI (same, plus dependency resolution and --json output)
npx @kura-ui/cli add agent-orb
# npm package
npm install @kura-ui/react
```

## When to use

- The central visual of a voice agent or call screen: idle, listening, thinking, speaking, error.
- Showing that an assistant is hearing the user (mic level) or talking back (TTS level).
- A 'talk to the agent' entry point inside a button or a card.
- An ambient, branded presence for an AI assistant in an empty state.

## When not to use

- Precise audio feedback such as a recording meter or waveform — use audio-waveform or voice-dictation.
- Text chat 'thinking' feedback inside a message list — use thinking-indicator or shimmer-text.
- A full-bleed background — use mesh-gradient or aurora.
- More than one per view: the orb is the accent element; repeat it and it stops meaning anything.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `state` | `"idle" \| "listening" \| "thinking" \| "speaking" \| "error"` | `"idle"` | no | What the agent is doing. idle breathes slowly, listening ripples with the input level, thinking swirls, speaking pulses with the output level, error turns red and calms down. |
| `colors` | `"jade" \| "ocean" \| "amber" \| "graphite" \| readonly [string, string, string, string]` | `"jade"` | no | A palette preset, or four CSS colours `[deep, mid, bright, glint]` (OKLCH, hex, `var(--token)`…). jade is the Kura signal colour. |
| `analyser` | `AudioAnalyser` | — | no | From `useAudioAnalyser`. Its level drives the orb while listening or speaking. Read every frame on the GPU loop — no React re-renders. |
| `inputLevel` | `number` | — | no | Microphone level 0–1 used while `listening`. Overrides `analyser`. |
| `outputLevel` | `number` | — | no | Agent voice level 0–1 used while `speaking`. Overrides `analyser`. |
| `label` | `string` | — | no | Accessible text for the state. Default: Voice agent idle / Listening / Thinking / Speaking / Voice agent error. |
| `announce` | `boolean` | `true` | no | Render the label in a polite live region. Set false when several orbs are on screen or a parent already announces the state. |
| `maxDpr` | `number` | `2` | no | Device-pixel-ratio cap. |

Native attributes of the root element, `className` and `ref` are passed through.

## Anatomy

- **AgentOrb** (`data-slot="agent-orb"`) — Square root (`aspect-square`); size it with a width class. `data-state` mirrors `state`.
- **ShaderCanvas** (`data-slot="agent-orb-canvas"`) — The WebGL sphere and its halo (aria-hidden). The sphere fills ~70% of the box.
- **Fallback** (`data-slot="agent-orb-fallback"`) — CSS gradient sphere used when WebGL2 is unavailable; it still spins while thinking.

## Accessibility

- Role: `status`
- The canvas is decorative (aria-hidden). The state is exposed as visually hidden text in a role=status live region, announced politely when it changes.
- Audio levels are never announced. Pass `label` to describe custom situations (e.g. “Muted”).
- If the orb is inside a button, give the button its own aria-label and set `announce={false}` to avoid double announcements.
- Reduced motion: No breathing, swirl, flow or audio reaction: a still frame per state. State changes cross-fade colour and brightness over ~0.4s, then rendering stops.

## Notes for agents

- Give it a width (`className="size-48"` or `w-full max-w-64`); it is square. The sphere fills ~70% so the halo has room — do not clip it with overflow-hidden.
- For real audio: `const mic = useAudioAnalyser({ source: micStream })` for listening and a second analyser on the TTS <audio> element for speaking; switch `analyser` with the state. For demos use `useAudioAnalyser({ simulate: "speech" })`.
- `inputLevel`/`outputLevel` are fine for levels you already have (e.g. from a WebRTC SDK) at ≤ 30 updates/s; the shader smooths them.
- Changing `state` never restarts the animation: uniforms ease toward the new state, so you can flip states as fast as your agent emits events.
- Only one orb per view should be animated; for lists of agents use a static avatar.

## Examples

### Idle orb (minimal)

Size it with a class; it breathes slowly.

```tsx
import { AgentOrb } from "@kura-ui/react/agent-orb";

export function AgentOrbMinimal() {
  return <AgentOrb className="size-48" />;
}
```

### States, palettes and audio (full)

Every state and preset, driven by a simulated speech analyser.

```tsx
"use client";

import * as React from "react";
import { useAudioAnalyser } from "@kura-ui/react/hooks";
import { Button } from "@kura-ui/react/button";
import { AgentOrb, type AgentOrbPreset, type AgentOrbState } from "@kura-ui/react/agent-orb";

const states: AgentOrbState[] = ["idle", "listening", "thinking", "speaking", "error"];

const presets: AgentOrbPreset[] = ["jade", "ocean", "amber", "graphite"];

export function AgentOrbFull() {
  const [state, setState] = React.useState<AgentOrbState>("speaking");
  const [preset, setPreset] = React.useState<AgentOrbPreset>("jade");
  // Simulated audio for the demo; pass `source: micStream` in a real app.
  const analyser = useAudioAnalyser({ simulate: "speech" });
  return (
    <div className="flex w-full max-w-md flex-col items-center gap-5">
      <AgentOrb state={state} colors={preset} analyser={analyser} className="size-64" />
      <div
        role="radiogroup"
        aria-label="Agent state"
        className="flex flex-wrap justify-center gap-1"
      >
        {states.map((s) => (
          <Button
            key={s}
            size="sm"
            variant={s === state ? "secondary" : "ghost"}
            role="radio"
            aria-checked={s === state}
            onClick={() => setState(s)}
            className="capitalize"
          >
            {s}
          </Button>
        ))}
      </div>
      <div role="radiogroup" aria-label="Palette" className="flex gap-1">
        {presets.map((p) => (
          <Button
            key={p}
            size="xs"
            variant={p === preset ? "secondary" : "ghost"}
            role="radio"
            aria-checked={p === preset}
            onClick={() => setPreset(p)}
            className="capitalize"
          >
            {p}
          </Button>
        ))}
      </div>
    </div>
  );
}
```

### All five states (state)

idle, listening, thinking, speaking and error side by side.

```tsx
"use client";

import { useAudioAnalyser } from "@kura-ui/react/hooks";
import { AgentOrb, type AgentOrbState } from "@kura-ui/react/agent-orb";

const states: AgentOrbState[] = ["idle", "listening", "thinking", "speaking", "error"];

export function AgentOrbStates() {
  const analyser = useAudioAnalyser({ simulate: "speech" });
  return (
    <div className="grid w-full grid-cols-5 gap-2">
      {states.map((s) => (
        <figure key={s} className="flex flex-col items-center gap-1">
          <AgentOrb state={s} analyser={analyser} announce={false} className="w-full max-w-32" />
          <figcaption className="text-kura-fg-subtle text-xs capitalize">{s}</figcaption>
        </figure>
      ))}
    </div>
  );
}
```

### Voice session card (composition)

A scripted call with captions, ShimmerText while thinking and IconButton controls.

```tsx
"use client";

import { Mic, MicOff, PhoneOff } from "lucide-react";
import * as React from "react";
import { useAudioAnalyser } from "@kura-ui/react/hooks";
import { IconButton } from "@kura-ui/react/icon-button";
import { ShimmerText } from "@kura-ui/react/shimmer-text";
import { AgentOrb, type AgentOrbState } from "@kura-ui/react/agent-orb";

const script: Array<{ state: AgentOrbState; ms: number; caption: string }> = [
  { state: "listening", ms: 3200, caption: "Listening…" },
  { state: "thinking", ms: 2400, caption: "Checking your calendar…" },
  { state: "speaking", ms: 4200, caption: "You're free after 3pm on Thursday." },
];

export function AgentOrbVoiceSession() {
  const [step, setStep] = React.useState(0);
  const [muted, setMuted] = React.useState(false);
  const analyser = useAudioAnalyser({ simulate: "speech" });
  const current = script[step % script.length]!;
  React.useEffect(() => {
    const id = setTimeout(() => setStep((s) => s + 1), current.ms);
    return () => clearTimeout(id);
  }, [current]);
  const state: AgentOrbState = muted && current.state === "listening" ? "idle" : current.state;
  return (
    <div className="flex w-full max-w-sm flex-col items-center gap-4 rounded-kura-2xl bg-kura-surface p-6 shadow-kura-md">
      <AgentOrb
        state={state}
        analyser={analyser}
        label={muted ? "Muted" : undefined}
        className="size-44"
      />
      <p className="flex h-10 items-center text-center text-kura-fg-muted text-sm" aria-hidden>
        {state === "thinking" ? <ShimmerText>{current.caption}</ShimmerText> : current.caption}
      </p>
      <div className="flex items-center gap-2">
        <IconButton
          label={muted ? "Unmute" : "Mute"}
          variant="secondary"
          size="lg"
          aria-pressed={muted}
          icon={muted ? <MicOff /> : <Mic />}
          onClick={() => setMuted((m) => !m)}
        />
        <IconButton label="End call" variant="danger" size="lg" icon={<PhoneOff />} />
      </div>
    </div>
  );
}
```

## Dependencies

- npm: none
- Kura registry items: `kura-theme`, `kura-merge-refs`, `kura-shader-color`, `shader-canvas`, `use-audio-analyser`, `use-reduced-motion`, `utils`
- Related: `voice-dictation`, `audio-waveform`, `thinking-indicator`, `mesh-gradient`, `shader-canvas`

---

# Agent Timeline

> Vertical plan tracker for multi-step agents: queued/active/done/failed/skipped steps, nested sub-steps, live durations and a connector that fills.

- **Slug:** `agent-timeline` · **Category:** agent · **Status:** beta
- **Import:** `import { AgentStepStatus, AgentTimeline, AgentTimelineStep } from "@kura-ui/react/agent-timeline";`
- **Docs:** https://kuro.abstergo.fyi/components/agent-timeline
- **Registry item:** https://kuro.abstergo.fyi/r/agent-timeline.json
- **Tags:** agent, plan, timeline, steps, progress, todo, stepper, tasks

## Install

```bash
# shadcn registry (copies source into your project)
npx shadcn@latest add https://kuro.abstergo.fyi/r/agent-timeline.json
# Kura CLI (same, plus dependency resolution and --json output)
npx @kura-ui/cli add agent-timeline
# npm package
npm install @kura-ui/react
```

## When to use

- Show an agent's plan and its progress (coding agents, research agents, deploy pipelines driven by a model).
- Show a todo list the model maintains (Claude Code / Cursor style task lists) with the current step highlighted.
- Nest sub-steps under a step, or attach a ToolCall / CodeBlock to a step via `content`.

## When not to use

- A single tool invocation — use tool-call.
- Free-form model thinking — use reasoning.
- Generic (non-agent) wizards or checkout steppers — use a regular stepper; the active state here uses the AI signal colour.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `steps` | `readonly AgentTimelineStep[]` | — | yes | The plan, in display order. AgentTimelineStep = { id, title, status: "queued" \| "active" \| "done" \| "failed" \| "skipped", description?, duration? (ms), startedAt?, steps? (nested), content? }. |
| `label` | `string` | `"Agent progress"` | no | Accessible name of the list (e.g. the task name). |
| `size` | `"sm" \| "md"` | `"md"` | no | md for plan panels, sm for dense sidebars. Nested sub-steps always render at sm. |

Native attributes of the root element, `className` and `ref` are passed through.

## Anatomy

- **AgentTimeline** (`data-slot="agent-timeline"`) — Root. `data-size`, `data-progress="done/total"`; contains a polite status region.
- **List** (`data-slot="agent-timeline-list"`) — The <ol> (nested lists for sub-steps).
- **Step** (`data-slot="agent-timeline-step"`) — <li> with `data-status`; the active step has `aria-current="step"`.
- **Node** (`data-slot="agent-timeline-node"`) — Status node: hollow ring (queued), jade pulse (active), check (done), cross (failed), dash (skipped).
- **Connector** (`data-slot="agent-timeline-connector"`) — Hairline track to the next step; its fill scales in from the top (`data-filled`) once the step is done or skipped.
- **Title** (`data-slot="agent-timeline-title"`) — Shimmers while active; struck through when skipped.
- **Duration** (`data-slot="agent-timeline-duration"`) — Mono tabular duration; ticks live for the active step.
- **Description** (`data-slot="agent-timeline-description"`) — Muted secondary line (danger-tinted on failure).
- **Content** (`data-slot="agent-timeline-content"`) — The step's `content` slot.

## Accessibility

- Role: `list`
- Rendered as an ordered list; each step's status is spoken after its title (“Edit files (in progress)”) and the active step has aria-current="step".
- A polite status region announces “Step 3 of 5”, “A step failed” or “All steps complete” — the live timers are never announced.
- Nodes and connectors are decorative (aria-hidden); status is never conveyed by colour alone.
- Reduced motion: The active pulse and title shimmer stop; connectors fade in instead of growing; check/cross icons appear without scale.

## Notes for agents

- Keep `id`s stable across updates so timers and connector transitions animate instead of remounting.
- Only one step should be `active` at a time per level; it carries the jade signal.
- Pass `duration` (ms) for finished steps; omit it for the active step to get a live timer (or pass `startedAt` from your server).
- Map a model-maintained todo list: pending → queued, in_progress → active, completed → done.

## Examples

### Three steps (minimal)

Done, active and queued.

```tsx
import { AgentTimeline } from "@kura-ui/react/agent-timeline";

export function AgentTimelineMinimal() {
  return (
    <AgentTimeline
      className="w-full max-w-md"
      steps={[
        { id: "read", title: "Read the failing test", status: "done", duration: 1200 },
        { id: "fix", title: "Patch the date parser", status: "active" },
        { id: "verify", title: "Re-run the test suite", status: "queued" },
      ]}
    />
  );
}
```

### Live agent run (full)

A plan that progresses on its own: live timers, nested sub-steps, a description, filling connectors.

```tsx
"use client";

import { RotateCcw } from "lucide-react";
import * as React from "react";
import { Button } from "@kura-ui/react/button";
import { AgentTimeline, type AgentTimelineStep } from "@kura-ui/react/agent-timeline";

const PLAN: Plan[] = [
  { id: "explore", title: "Explore the repository", ms: 1400 },
  {
    id: "plan",
    title: "Plan the migration",
    ms: 2200,
    sub: [
      { id: "plan-a", title: "List call sites of fetchUser()" },
      { id: "plan-b", title: "Check the auth middleware" },
    ],
  },
  { id: "edit", title: "Edit 4 files", ms: 2600 },
  { id: "test", title: "Run the test suite", ms: 2000 },
  { id: "pr", title: "Open a pull request", ms: 1200 },
];

function stepsAt(cursor: number, startedAt: number | undefined): AgentTimelineStep[] {
  return PLAN.map((p, i) => ({
    id: p.id,
    title: p.title,
    status: i < cursor ? "done" : i === cursor ? "active" : "queued",
    duration: i < cursor ? p.ms : undefined,
    startedAt: i === cursor ? startedAt : undefined,
    description: p.id === "edit" && i <= cursor ? "src/api/user.ts, src/lib/auth.ts +2" : undefined,
    steps: p.sub?.map((s, j) => ({
      id: s.id,
      title: s.title,
      status:
        i < cursor ? "done" : i === cursor ? (j === 0 ? "done" : "active") : ("queued" as const),
      duration: i < cursor || (i === cursor && j === 0) ? 800 + j * 400 : undefined,
    })),
  }));
}

export function AgentTimelineFull() {
  const [cursor, setCursor] = React.useState(0);
  const [startedAt, setStartedAt] = React.useState<number>();
  const [run, setRun] = React.useState(0);

  // biome-ignore lint/correctness/useExhaustiveDependencies: `run` replays the plan
  React.useEffect(() => {
    let i = 0;
    setCursor(0);
    setStartedAt(Date.now());
    let id: ReturnType<typeof setTimeout>;
    const next = () => {
      id = setTimeout(() => {
        i++;
        setCursor(i);
        setStartedAt(Date.now());
        if (i < PLAN.length) next();
      }, PLAN[i]!.ms);
    };
    next();
    return () => clearTimeout(id);
  }, [run]);

  const done = cursor >= PLAN.length;
  return (
    <div className="flex w-full max-w-md flex-col gap-4">
      <AgentTimeline steps={stepsAt(cursor, startedAt)} label="Migration plan" size="md" />
      <div className="flex items-center justify-between">
        <span className="font-kura-mono text-kura-fg-subtle text-xs tabular-nums">
          {Math.min(cursor, PLAN.length)}/{PLAN.length} steps
        </span>
        <Button variant="secondary" size="sm" disabled={!done} onClick={() => setRun((r) => r + 1)}>
          <RotateCcw /> Replay
        </Button>
      </div>
    </div>
  );
}
```

### Every state, small (state)

Done, skipped, failed and queued at size sm.

```tsx
import { AgentTimeline } from "@kura-ui/react/agent-timeline";

export function AgentTimelineStates() {
  return (
    <AgentTimeline
      size="sm"
      className="w-full max-w-sm"
      steps={[
        { id: "1", title: "Install dependencies", status: "done", duration: 8300 },
        { id: "2", title: "Generate types", status: "skipped", description: "Already up to date" },
        {
          id: "3",
          title: "Build the docs",
          status: "failed",
          duration: 21_400,
          description: "next build exited with code 1",
        },
        { id: "4", title: "Deploy preview", status: "queued" },
      ]}
    />
  );
}
```

### Steps with tool calls (composition)

Inline ToolCalls attached to steps through `content`, inside a task card.

```tsx
import { FileText, Terminal } from "lucide-react";
import { ToolCall } from "@kura-ui/react/tool-call";
import { AgentTimeline } from "@kura-ui/react/agent-timeline";

export function AgentTimelineWithTools() {
  return (
    <div className="flex w-full max-w-lg flex-col gap-4 rounded-kura-xl bg-kura-surface p-4 shadow-kura-sm">
      <div className="flex items-baseline justify-between">
        <h3 className="font-medium text-kura-fg text-sm">Fix flaky date test</h3>
        <span className="font-kura-mono text-kura-fg-subtle text-xs tabular-nums">2/3</span>
      </div>
      <AgentTimeline
        label="Fix flaky date test"
        steps={[
          {
            id: "read",
            title: "Read the failing test",
            status: "done",
            duration: 900,
            content: (
              <ToolCall
                variant="inline"
                name="read_file"
                icon={<FileText />}
                status="success"
                duration={120}
                args={{ path: "src/date.test.ts" }}
              />
            ),
          },
          {
            id: "run",
            title: "Reproduce with a fixed timezone",
            status: "active",
            content: (
              <ToolCall
                variant="inline"
                name="run_command"
                icon={<Terminal />}
                status="running"
                args={{ command: "TZ=Pacific/Auckland pnpm test date" }}
              />
            ),
          },
          { id: "fix", title: "Patch and verify", status: "queued" },
        ]}
      />
    </div>
  );
}
```

## Dependencies

- npm: `lucide-react`
- Kura registry items: `kura-theme`, `shimmer-text`, `utils`
- Related: `tool-call`, `reasoning`, `approval-prompt`, `shimmer-text`

---

# Approval Prompt

> Human-in-the-loop permission card (“Kura wants to run `rm -rf build`”) with risk level, details, Approve/Deny/Always allow, ⌘↵ and Esc, and resolved states.

- **Slug:** `approval-prompt` · **Category:** agent · **Status:** beta
- **Import:** `import { ApprovalDecision, ApprovalPrompt } from "@kura-ui/react/approval-prompt";`
- **Docs:** https://kuro.abstergo.fyi/components/approval-prompt
- **Registry item:** https://kuro.abstergo.fyi/r/approval-prompt.json
- **Tags:** approval, permission, human-in-the-loop, confirm, agent, security, shortcuts, consent

## Install

```bash
# shadcn registry (copies source into your project)
npx shadcn@latest add https://kuro.abstergo.fyi/r/approval-prompt.json
# Kura CLI (same, plus dependency resolution and --json output)
npx @kura-ui/cli add approval-prompt
# npm package
npm install @kura-ui/react
```

## When to use

- An agent needs explicit permission before a side effect: running a shell command, editing files, sending email, spending money, calling a destructive API.
- Show exactly what will run (verbatim command) and how risky it is before the user decides.
- Offer “Always allow” for a class of actions in this session (persist the rule yourself in onAlwaysAllow).
- Keep the decision visible in the transcript afterwards (Approved / Denied / Always allowed) without the card changing height.

## When not to use

- Showing a tool call that does not need permission — use tool-call (it also has an awaiting-approval status for compact inline approvals).
- Generic confirm dialogs unrelated to an agent (deleting a document) — use a dialog.
- Progress of a multi-step plan — use agent-timeline.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `title` | `React.ReactNode` | — | yes | What the agent wants, e.g. "Kura wants to run a command". Labels the region. |
| `command` | `string` | — | no | The exact command/action, shown verbatim in mono after a $ prompt (wraps, never truncated). |
| `description` | `React.ReactNode` | — | no | Why and what it touches; becomes the region's accessible description. |
| `risk` | `"low" \| "medium" \| "high"` | `"medium"` | no | Badge (green/amber/red dot). high also turns Approve into a red “Run anyway” button. |
| `details` | `React.ReactNode` | — | no | Content behind a “Details” expander: a diff (CodeBlock), arguments, affected files. |
| `decision` | `"pending" \| "approved" \| "denied" \| "always"` | — | no | Decision (controlled). |
| `defaultDecision` | `"pending" \| "approved" \| "denied" \| "always"` | `"pending"` | no | Initial decision when uncontrolled (use a resolved value to render history). |
| `onDecisionChange` | `(decision: ApprovalDecision) => void` | — | no | Called with every decision. |
| `onApprove` | `() => void` | — | no | Called on Approve (button or ⌘/Ctrl+Enter). |
| `onDeny` | `() => void` | — | no | Called on Deny (button or Esc). |
| `onAlwaysAllow` | `() => void` | — | no | Shows an “Always allow” ghost button; called when chosen. |
| `shortcuts` | `boolean` | `true` | no | Bind ⌘/Ctrl+Enter (approve) and Esc (deny) on the document while pending, and show the keys on the buttons. Only one prompt on screen should bind them. |
| `approveLabel` | `string` | — | no | Approve label. Default “Approve”, or “Run anyway” for high risk. |
| `denyLabel` | `string` | `"Deny"` | no | Deny label. |
| `alwaysAllowLabel` | `string` | `"Always allow"` | no | Always-allow label. |
| `icon` | `React.ReactNode` | — | no | Icon in the header tile. Default a terminal. |

Native attributes of the root element, `className` and `ref` are passed through.

## Anatomy

- **ApprovalPrompt** (`data-slot="approval-prompt"`) — <section> labelled by the title and the command (so stacked prompts have distinct names). `data-decision="pending" | "approved" | "denied" | "always"`, `data-risk`.
- **Title** (`data-slot="approval-prompt-title"`) — Heading; mutes once resolved.
- **Risk** (`data-slot="approval-prompt-risk"`) — Risk badge with a coloured dot and text.
- **Command** (`data-slot="approval-prompt-command"`) — Mono command well; the <code> is `approval-prompt-code`.
- **Details** (`data-slot="approval-prompt-details"`) — Collapsible details (grid-rows transition, inert when closed).
- **Footer** (`data-slot="approval-prompt-footer"`) — Fixed-height footer holding actions and the resolution, so resolving never shifts layout.
- **Waiting** (`data-slot="approval-prompt-waiting"`) — Jade “Needs approval” pill — the view's one accent while pending.
- **Actions** (`data-slot="approval-prompt-actions"`) — Always allow / Deny (Esc) / Approve (⌘↵); inert once resolved.
- **Resolution** (`data-slot="approval-prompt-resolution"`) — role="status" line that cross-fades in: Approved / Denied / Always allowed.

## Accessibility

- Role: `region`
- A <section> labelled by the title and described by the description, so screen-reader users land on the whole request.
- Buttons expose their shortcuts with aria-keyshortcuts; keycaps are also rendered visually.
- The resolution is a status region, so the decision is announced; the action row becomes inert and hidden.
- Risk is conveyed in text (“High risk”), not only colour. No dark patterns: Deny is as prominent as Approve.
- Reduced motion: The waiting pulse stops and resolved states cross-fade without blur; details open without height travel.

| Keys | Action |
| --- | --- |
| Mod+Enter | Approve (while pending, when shortcuts is on) |
| Escape | Deny (while pending, when shortcuts is on; not while typing in an input) |
| Tab | Details, Always allow, Deny, Approve |

## Notes for agents

- Show the command verbatim — never paraphrase what will run.
- The decision is only UI state: actually gate the side effect on onApprove / onDecisionChange in your agent loop.
- Render past prompts with `defaultDecision` (or controlled `decision`) set to the stored outcome and `shortcuts={false}`.
- When several prompts are visible, enable `shortcuts` on the newest pending one only.

## Examples

### Low-risk command (minimal)

Title, command and risk.

```tsx
import { ApprovalPrompt } from "@kura-ui/react/approval-prompt";

export function ApprovalPromptMinimal() {
  return (
    <ApprovalPrompt
      title="Kura wants to run a command"
      command="pnpm install"
      risk="low"
      shortcuts={false}
      className="w-full max-w-lg"
    />
  );
}
```

### High-risk, every option (full)

Description, details, controlled decision, callbacks, Always allow, custom labels and ⌘↵ / Esc.

```tsx
"use client";

import { RotateCcw } from "lucide-react";
import * as React from "react";
import { Button } from "@kura-ui/react/button";
import { type ApprovalDecision, ApprovalPrompt } from "@kura-ui/react/approval-prompt";

export function ApprovalPromptFull() {
  const [decision, setDecision] = React.useState<ApprovalDecision>("pending");
  const [log, setLog] = React.useState<string[]>([]);
  const note = (s: string) => setLog((l) => [...l.slice(-2), s]);
  return (
    <div className="flex w-full max-w-lg flex-col gap-3">
      <ApprovalPrompt
        title="Kura wants to delete a directory"
        command="rm -rf build"
        description="Clears stale output before rebuilding. Affects 1,204 files under ./build only."
        risk="high"
        details={
          <ul className="flex list-disc flex-col gap-1 pl-4">
            <li>Working directory: ~/code/kura-ui</li>
            <li>Requested by step 3 of 5, “Rebuild the docs”</li>
            <li>Not tracked by git — cannot be restored from history</li>
          </ul>
        }
        decision={decision}
        onDecisionChange={setDecision}
        onApprove={() => note("approved")}
        onDeny={() => note("denied")}
        onAlwaysAllow={() => note("always allowed")}
        shortcuts
        approveLabel="Run anyway"
        denyLabel="Deny"
        alwaysAllowLabel="Always allow"
      />
      <div className="flex items-center justify-between">
        <span className="font-kura-mono text-kura-fg-subtle text-xs">
          {log.length ? log.join(" → ") : "Try ⌘↵ or Esc"}
        </span>
        <Button
          variant="ghost"
          size="sm"
          disabled={decision === "pending"}
          onClick={() => setDecision("pending")}
        >
          <RotateCcw /> Reset
        </Button>
      </div>
    </div>
  );
}
```

### Resolved states (state)

Approved, denied and always-allowed, as they appear in history.

```tsx
"use client";

import { ApprovalPrompt } from "@kura-ui/react/approval-prompt";

export function ApprovalPromptResolved() {
  return (
    <div className="flex w-full max-w-lg flex-col gap-3">
      <ApprovalPrompt
        title="Kura wants to run a command"
        command="git push origin main"
        risk="medium"
        defaultDecision="approved"
        shortcuts={false}
      />
      <ApprovalPrompt
        title="Kura wants to run a command"
        command="curl -X DELETE https://api.example.com/v1/projects/42"
        risk="high"
        defaultDecision="denied"
        shortcuts={false}
      />
      <ApprovalPrompt
        title="Kura wants to read a file"
        command="cat .env.example"
        risk="low"
        defaultDecision="always"
        onAlwaysAllow={() => {}}
        shortcuts={false}
      />
    </div>
  );
}
```

### Approve a file edit (composition)

A diff CodeBlock in the details, driving a ToolCall's status.

```tsx
"use client";

import { FilePen } from "lucide-react";
import * as React from "react";
import { CodeBlock } from "@kura-ui/react/code-block";
import { ToolCall } from "@kura-ui/react/tool-call";
import { type ApprovalDecision, ApprovalPrompt } from "@kura-ui/react/approval-prompt";

const DIFF = `@@ -1,4 +1,5 @@
 export const config = {
-  retries: 1,
+  retries: 3,
+  backoff: "exponential",
   timeout: 12_000,
 };`;

export function ApprovalPromptWithDiff() {
  const [decision, setDecision] = React.useState<ApprovalDecision>("pending");
  return (
    <div className="flex w-full max-w-lg flex-col gap-2">
      <ToolCall
        name="edit_file"
        title="Edit src/config.ts"
        icon={<FilePen />}
        status={
          decision === "pending" ? "awaiting-approval" : decision === "denied" ? "error" : "success"
        }
        error={decision === "denied" ? "Denied by user." : undefined}
        duration={decision === "approved" ? 240 : undefined}
        summary="+2 −1"
      />
      <ApprovalPrompt
        title="Apply this edit?"
        icon={<FilePen />}
        risk="low"
        decision={decision}
        onDecisionChange={setDecision}
        shortcuts={false}
        approveLabel="Apply"
        details={<CodeBlock code={DIFF} language="ts" diff header={false} />}
      />
    </div>
  );
}
```

## Dependencies

- npm: `lucide-react`
- Kura registry items: `kura-theme`, `button`, `kbd`, `use-controllable-state`, `use-hotkey`, `utils`
- Related: `tool-call`, `agent-timeline`, `code-block`, `kbd-shortcut`

---

# Artifact Card

> Card for something an agent made — document, code, web page, image, sheet or diagram — with generating/updating progress, versions and open-in-panel.

- **Slug:** `artifact-card` · **Category:** conversation · **Status:** beta
- **Import:** `import { ArtifactCard, ArtifactKind, ArtifactStatus } from "@kura-ui/react/artifact-card";`
- **Docs:** https://kuro.abstergo.fyi/components/artifact-card
- **Registry item:** https://kuro.abstergo.fyi/r/artifact-card.json
- **Tags:** artifact, canvas, document, file, output, generation, versions, preview

## Install

```bash
# shadcn registry (copies source into your project)
npx shadcn@latest add https://kuro.abstergo.fyi/r/artifact-card.json
# Kura CLI (same, plus dependency resolution and --json output)
npx @kura-ui/cli add artifact-card
# npm package
npm install @kura-ui/react
```

## When to use

- An assistant message produced a standalone deliverable (a document, a code file, a web page, an image, a CSV, a diagram) that the user opens in a side panel or another page.
- Show an artifact while the agent is still writing it: status="generating" with a live statusText and optional progress, then flip to "ready".
- An artifact the user asked to change: status="updating" plus a ‹ v2/3 › version switcher (versions/version/onVersionChange).
- A list of everything the agent made in a session, e.g. a files/outputs sidebar (compact variant, selected marks the one that is open).
- A visual card with a thumbnail of the artifact under the title (variant="preview" with a `preview` node: a text excerpt, an <img>, a headerless CodeBlock).

## When not to use

- Code the user should read inline in the answer — use code-block directly.
- A file the user uploaded or attached to the prompt — use attachment.
- One tool invocation with arguments and a result (read_file, run_command) — use tool-call.
- A link to an external web source the answer relies on — use citation.
- A multi-step plan of work — use agent-timeline.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `title` | `string` | — | yes | The artifact's name, e.g. "Q3 launch plan" or "pricing-table.tsx". Truncates. |
| `kind` | `"document" \| "code" \| "web" \| "image" \| "data" \| "diagram" \| "file"` | `"document"` | no | What the agent made. Picks the icon, the spoken label (Document, Code, Web page, Image, Spreadsheet, Diagram, File) and the preview placeholder. |
| `status` | `"generating" \| "updating" \| "ready" \| "error"` | `"ready"` | no | Lifecycle. generating = first write and updating = an edit (both: jade icon tile, shimmering statusText, progress bar, aria-busy); error = danger tile and message. |
| `meta` | `React.ReactNode` | — | no | Secondary line when ready, e.g. "Markdown · 1,240 words" or "TypeScript · 94 lines". Default: the kind label. |
| `statusText` | `React.ReactNode` | — | no | Live line while busy, e.g. "Writing section 3 of 5…". Default "Generating…" / "Updating…". Not announced on every change. |
| `error` | `React.ReactNode` | — | no | Message for status="error". Default "Couldn't finish". |
| `progress` | `number` | — | no | Completion 0–1 while busy: a determinate bar plus a mono percentage. Omit for an indeterminate sweep. |
| `icon` | `React.ReactNode` | — | no | Replaces the kind icon (lucide). |
| `variant` | `"compact" \| "preview"` | `"compact"` | no | compact = one-row chip sized to its content, for message text and lists; preview = full-width card with a 144px thumbnail area above the title. |
| `preview` | `React.ReactNode` | — | no | Thumbnail content for variant="preview": a text excerpt, an <img className="size-full object-cover">, a headerless CodeBlock. It fades out at the bottom and is aria-hidden/inert. Default: a sketch of the kind that shimmers while busy. |
| `versions` | `number` | `1` | no | Number of versions. Above 1 shows a ‹ v2/3 › switcher (disabled while busy). |
| `version` | `number` | — | no | Shown version, 1-based (controlled). |
| `defaultVersion` | `number` | — | no | Initial version when uncontrolled. Default: the latest (`versions`). |
| `onVersionChange` | `(version: number) => void` | — | no | Called with the new 1-based version from the switcher. |
| `onOpen` | `() => void` | — | no | Open the artifact, e.g. into a side panel. The title becomes a button stretched over the whole card. |
| `href` | `string` | — | no | Open by navigating instead: the title becomes a link stretched over the card. |
| `selected` | `boolean` | `false` | no | This artifact is the one currently open (e.g. in the side panel): a stronger ring and aria-current on the open control. |
| `onRetry` | `() => void` | — | no | Shows a Retry icon button when status="error". |
| `actions` | `React.ReactNode` | — | no | Extra controls at the end of the row, e.g. Copy / Download IconButtons with size="sm". They sit above the stretched open target. |

Native attributes of the root element, `className` and `ref` are passed through.

## Anatomy

- **ArtifactCard** (`data-slot="artifact-card"`) — Root. `data-kind`, `data-status`, `data-variant`, `data-selected`; `aria-busy` while generating/updating.
- **Preview** (`data-slot="artifact-card-preview"`) — Thumbnail area (variant="preview" only), aria-hidden and inert.
- **Header** (`data-slot="artifact-card-header"`) — Row with icon, title, meta, versions and actions.
- **Icon** (`data-slot="artifact-card-icon"`) — 36px kind tile; jade while busy, danger on error.
- **Open** (`data-slot="artifact-card-open"`) — The title as a button (onOpen) or link (href) whose ::after covers the card. Without either, the title renders as `artifact-card-title`.
- **Meta** (`data-slot="artifact-card-meta"`) — Second line: meta, shimmering statusText + percentage, or the error.
- **Versions** (`data-slot="artifact-card-versions"`) — ‹ v2/3 › switcher, read as “Version 2 of 3”.
- **Actions** (`data-slot="artifact-card-actions"`) — Retry (on error) and your `actions`.
- **Progress** (`data-slot="artifact-card-progress"`) — 2px role=progressbar at the bottom edge (of the preview, or of the compact card) while busy.

## Accessibility

- The open control is a real button or link named “<title>, <kind>[, generating | , updating | , failed]”; its ::after stretches over the card so the whole card is clickable while Versions and Actions stay separate tab stops.
- `selected` sets aria-current on the open control.
- The preview thumbnail is decorative (aria-hidden + inert): put anything a screen-reader user needs into title/meta.
- A polite status region announces lifecycle changes (“Generating Pricing page”, “Pricing page ready”, “… failed”); statusText and progress ticks are not announced.
- While busy the root has aria-busy and the bar is a named role=progressbar (with aria-valuenow when `progress` is given).
- Reduced motion: The shimmer and the indeterminate sweep stop (a still tinted track remains); the hover zoom of the preview, the press scale and the chevron nudge are removed. Colour and opacity changes stay.

| Keys | Action |
| --- | --- |
| Tab | Open control, then the version arrows, Retry and your actions |
| Enter / Space | Open the artifact (Enter follows the link for href) |

## Notes for agents

- Keep the same card mounted from generating → ready so the transition (and the single announcement) is smooth; switch `status`, don't swap components.
- Drive `selected` from the id of the artifact open in your panel, so the card the user is looking at is marked.
- Use variant="compact" inside message text and lists (it sizes to content — give it a width like w-full or max-w-sm when stacking); use "preview" when there is room for a thumbnail.
- For images pass preview={<img src={url} alt="" className="size-full object-cover" />} — the thumbnail is decorative, the title carries the name.
- Pass `progress` only when you really know it (e.g. sections written / planned); otherwise leave it out for the indeterminate sweep.
- Map Anthropic/OpenAI canvas or artifact tool calls (create → generating, update/rewrite → updating with versions + 1) onto one card per artifact id.

## Examples

### Compact card (minimal)

Title, meta and an open action that toggles `selected`.

```tsx
"use client";

import * as React from "react";
import { ArtifactCard } from "@kura-ui/react/artifact-card";

export function ArtifactCardMinimal() {
  const [open, setOpen] = React.useState(false);
  return (
    <ArtifactCard
      title="Q3 launch plan"
      kind="document"
      meta="Markdown · 1,240 words"
      selected={open}
      onOpen={() => setOpen((o) => !o)}
      className="w-80"
    />
  );
}
```

### Written live, then edited (full)

Preview variant generating with progress and statusText, then ready with versions, Copy/Download actions and an edit that creates v2.

```tsx
"use client";

import { Copy, Download, RotateCcw } from "lucide-react";
import * as React from "react";
import { Button } from "@kura-ui/react/button";
import { IconButton } from "@kura-ui/react/icon-button";
import { ArtifactCard } from "@kura-ui/react/artifact-card";

const PLAN = [
  "Pricing page rewrite",
  "Lead with the outcome, not the plan names. Most visitors arrive from a comparison search and decide in the first screen.",
  "Collapse the four tiers into three. Team and Business overlap on every feature that matters to a buyer under fifty seats.",
  "Move the FAQ above the fold on mobile and answer the two questions sales hears most: data residency and seat changes.",
];

const STEPS = ["Outlining…", "Writing the summary…", "Writing section 2 of 3…", "Polishing…"];

export function ArtifactCardFull() {
  const [run, setRun] = React.useState(0);
  const [progress, setProgress] = React.useState(0);
  const [version, setVersion] = React.useState(1);
  const [open, setOpen] = React.useState(false);
  const busy = progress < 1;

  // biome-ignore lint/correctness/useExhaustiveDependencies: `run` restarts the simulation
  React.useEffect(() => {
    setProgress(0);
    const id = setInterval(() => {
      setProgress((p) => {
        const next = Math.min(1, p + 0.035 + Math.random() * 0.03);
        if (next >= 1) clearInterval(id);
        return next;
      });
    }, 140);
    return () => clearInterval(id);
  }, [run]);

  const visible = busy ? Math.max(1, Math.ceil(progress * PLAN.length)) : PLAN.length;
  const versions = run + 1;

  return (
    <div className="flex w-full max-w-sm flex-col gap-3">
      <ArtifactCard
        variant="preview"
        kind="document"
        title="Pricing page rewrite"
        status={busy ? (run === 0 ? "generating" : "updating") : "ready"}
        statusText={STEPS[Math.min(STEPS.length - 1, Math.floor(progress * STEPS.length))]}
        progress={progress}
        meta={`Markdown · ${version === versions ? "412" : "386"} words · edited just now`}
        versions={busy ? Math.max(1, versions - 1) : versions}
        version={busy ? Math.max(1, versions - 1) : version}
        onVersionChange={setVersion}
        selected={open}
        onOpen={() => setOpen((o) => !o)}
        actions={
          <>
            <IconButton size="sm" label="Copy" icon={<Copy />} disabled={busy} />
            <IconButton size="sm" label="Download" icon={<Download />} disabled={busy} />
          </>
        }
        preview={
          <div className="flex flex-col gap-2 p-5 text-[11px] text-kura-fg-muted leading-relaxed">
            {PLAN.slice(0, visible).map((line, i) =>
              i === 0 ? (
                <p key={line} className="font-semibold text-[13px] text-kura-fg tracking-tight">
                  {line}
                </p>
              ) : (
                <p key={line} className="animate-kura-fade-in">
                  {line}
                </p>
              ),
            )}
          </div>
        }
      />
      <div className="flex items-center justify-between text-kura-fg-subtle text-xs">
        <span>{open ? "Open in the side panel" : "Click the card to open it"}</span>
        <Button
          size="xs"
          variant="ghost"
          disabled={busy}
          onClick={() => {
            setRun((r) => r + 1);
            setVersion(run + 2);
          }}
        >
          <RotateCcw />
          Ask for an edit
        </Button>
      </div>
    </div>
  );
}
```

### Every status (state)

Generating (indeterminate), updating with progress and versions, ready, failed with Retry.

```tsx
"use client";

import { ArtifactCard } from "@kura-ui/react/artifact-card";

export function ArtifactCardStates() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-2.5">
      <ArtifactCard
        title="Onboarding email sequence"
        status="generating"
        statusText="Drafting email 2 of 4…"
        onOpen={() => {}}
        className="w-full"
      />
      <ArtifactCard
        kind="code"
        title="use-session.ts"
        status="updating"
        progress={0.64}
        statusText="Applying 3 edits…"
        versions={2}
        onOpen={() => {}}
        className="w-full"
      />
      <ArtifactCard
        kind="data"
        title="Churn by cohort"
        meta="CSV · 12 columns · 4,218 rows"
        onOpen={() => {}}
        className="w-full"
      />
      <ArtifactCard
        kind="web"
        title="Waitlist landing page"
        status="error"
        error="Stopped: the response hit the output limit"
        onRetry={() => {}}
        onOpen={() => {}}
        className="w-full"
      />
    </div>
  );
}
```

### Every kind (variant)

Document, code, web page, image, spreadsheet and diagram.

```tsx
"use client";

import * as React from "react";
import { ArtifactCard } from "@kura-ui/react/artifact-card";

const KINDS = [
  { kind: "document", title: "Board update — October", meta: "Markdown · 860 words" },
  { kind: "code", title: "rate-limiter.ts", meta: "TypeScript · 94 lines" },
  { kind: "web", title: "Pricing page", meta: "React · interactive" },
  { kind: "image", title: "Hero illustration", meta: "PNG · 1600 × 900" },
  { kind: "data", title: "Q3 pipeline", meta: "CSV · 1,204 rows" },
  { kind: "diagram", title: "Auth flow", meta: "Mermaid · 9 nodes" },
] as const;

export function ArtifactCardKinds() {
  return (
    <div className="grid w-full max-w-xl grid-cols-1 gap-2.5 sm:grid-cols-2">
      {KINDS.map((a) => (
        <ArtifactCard key={a.kind} {...a} onOpen={() => {}} className="w-full" />
      ))}
    </div>
  );
}
```

### In a message, opening a side panel (composition)

An assistant Message with a code artifact whose preview is a headerless CodeBlock; the card toggles a side panel with the full file.

```tsx
"use client";

import { X } from "lucide-react";
import * as React from "react";
import { CodeBlock } from "@kura-ui/react/code-block";
import { IconButton } from "@kura-ui/react/icon-button";
import { Message } from "@kura-ui/react/message";
import { ArtifactCard } from "@kura-ui/react/artifact-card";

const CODE = `import { Ratelimit } from "@upstash/ratelimit";
import { kv } from "@vercel/kv";

// 20 requests per 10 seconds, per user, sliding window.
export const limiter = new Ratelimit({
  redis: kv,
  limiter: Ratelimit.slidingWindow(20, "10 s"),
  prefix: "chat",
});

export async function guard(userId: string) {
  const { success, reset } = await limiter.limit(userId);
  if (!success) {
    const retry = Math.ceil((reset - Date.now()) / 1000);
    throw new Response("Slow down", {
      status: 429,
      headers: { "Retry-After": String(retry) },
    });
  }
}`;

export function ArtifactCardComposition() {
  const [open, setOpen] = React.useState(true);
  return (
    <div className="flex w-full max-w-3xl items-start gap-4">
      <div className="flex min-w-0 flex-1 flex-col gap-4">
        <Message from="user">Rate limit the chat route to 20 requests per 10 seconds.</Message>
        <Message from="assistant" name="Kura">
          <p>
            Here's a sliding-window limiter keyed by user. Call <code>guard()</code> at the top of
            the route; it throws a 429 with <code>Retry-After</code> when someone is over.
          </p>
          <ArtifactCard
            variant="preview"
            kind="code"
            title="rate-limiter.ts"
            meta="TypeScript · 21 lines"
            selected={open}
            onOpen={() => setOpen((o) => !o)}
            className="max-w-xs"
            preview={
              <CodeBlock
                code={CODE}
                language="ts"
                header={false}
                lineNumbers={false}
                copyable={false}
                className="rounded-none bg-transparent text-[11px] shadow-none"
              />
            }
          />
        </Message>
      </div>
      {open && (
        <section
          aria-label="rate-limiter.ts"
          className="hidden w-[22rem] shrink-0 animate-kura-fade-in flex-col overflow-hidden rounded-kura-xl bg-kura-surface shadow-kura-md md:flex"
        >
          <header className="flex h-11 items-center gap-2 pr-1.5 pl-3.5 shadow-[inset_0_-1px_0_var(--kura-border-subtle)]">
            <span className="min-w-0 flex-1 truncate font-medium text-sm">rate-limiter.ts</span>
            <IconButton size="sm" label="Close panel" icon={<X />} onClick={() => setOpen(false)} />
          </header>
          <CodeBlock
            code={CODE}
            language="ts"
            header={false}
            maxHeight={320}
            className="rounded-none text-xs shadow-none"
          />
        </section>
      )}
    </div>
  );
}
```

## Dependencies

- npm: `lucide-react`
- Kura registry items: `kura-theme`, `icon-button`, `shimmer-text`, `use-controllable-state`, `utils`
- Related: `message`, `code-block`, `attachment`, `tool-call`, `streaming-text`

---

# Attachment

> File and image attachment chips with thumbnails, upload progress rings, error/retry, remove, a “+N” overflow stack and a dropzone.

- **Slug:** `attachment` · **Category:** input · **Status:** beta
- **Import:** `import { Attachment, AttachmentDropzone, AttachmentItem, AttachmentKind, AttachmentList, AttachmentProgressRing, AttachmentStatus } from "@kura-ui/react/attachment";`
- **Docs:** https://kuro.abstergo.fyi/components/attachment
- **Registry item:** https://kuro.abstergo.fyi/r/attachment.json
- **Tags:** file, upload, attachment, image, thumbnail, dropzone, progress, drag-and-drop

## Install

```bash
# shadcn registry (copies source into your project)
npx shadcn@latest add https://kuro.abstergo.fyi/r/attachment.json
# Kura CLI (same, plus dependency resolution and --json output)
npx @kura-ui/cli add attachment
# npm package
npm install @kura-ui/react
```

## When to use

- Show files the user attached to a prompt before sending (inside or above a composer).
- Display upload progress, failures and a retry action for files sent to a model.
- Render the files that belong to a sent message or an agent artifact list.
- A standalone drop area for documents to index, e.g. “Add files to this project”.

## When not to use

- A complete prompt input with paste and drag-drop built in — use composer (it renders attachment for you).
- Rich previews of generated documents or code — use artifact-card or code-block.
- Audio recordings with playback — use audio-waveform with `peaks`.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `name` | `string` | — | yes | File name shown on the chip; long names truncate with an ellipsis. |
| `size` | `number` | — | no | Size in bytes, rendered as “2.4 MB”. |
| `type` | `string` | — | no | MIME type. Chooses the file-type icon (image, pdf, code, text, sheet, audio, video, archive) and whether a preview renders as a thumbnail. |
| `previewUrl` | `string` | — | no | Image URL (object URL or remote). With an image type the attachment renders as a 44px square thumbnail. |
| `status` | `"ready" \| "uploading" \| "error"` | `"ready"` | no | Upload state. Uploading shows a progress ring; error shows a danger tint. |
| `progress` | `number` | — | no | Upload progress 0..1 while uploading. Omit for an indeterminate spinning arc. |
| `error` | `string` | — | no | Error message for status=error; shown as the title and announced via role=alert. |
| `variant` | `"auto" \| "chip" \| "tile"` | `"auto"` | no | auto = thumbnail tile for images that have a previewUrl, a chip (icon + name + size) otherwise. |
| `onRemove` | `() => void` | — | no | Render a × button (revealed on hover/focus, always visible on touch). |
| `onRetry` | `() => void` | — | no | Render a Retry action while status is error. |

Native attributes of the root element, `className` and `ref` are passed through.

## Anatomy

- **Attachment** (`data-slot="attachment"`) — One file. Exposes data-variant (chip|tile), data-kind and data-status (ready|uploading|error).
- **AttachmentRemove** (`data-slot="attachment-remove"`) — The × button, labelled “Remove <name>”. Rendered when onRemove is set.
- **AttachmentList** (`data-slot="attachment-list"`) — Wrapping <ul> of attachments with pop-in/out and gap-closing layout motion, plus the “+N” stack.
  - `items`: `readonly AttachmentItem[]` — Items: { id, name, size?, type?, url?, status?, progress?, error?, file? }.
  - `onRemove`: `(id: string) => void` — Remove handler.
  - `onRetry`: `(id: string) => void` — Retry handler.
  - `max`: `number` — Show at most this many items, then a “+N” stack button that reveals the rest.
  - `variant`: `"auto" | "chip" | "tile"` = `"auto"` — Forwarded to every item.
  - `label`: `string` = `"Attachments"` — Accessible name of the list.
- **AttachmentOverflow** (`data-slot="attachment-overflow"`) — The “+N” stack button (a counter with two offset cards behind it).
- **AttachmentDropzone** (`data-slot="attachment-dropzone"`) — Click-to-browse + drop target with a dashed hairline. data-dragging is set only while a drag carries files.
  - `onFiles`: `(files: File[], rejected: File[]) => void` — Accepted files, and those rejected by accept/maxSize.
  - `accept`: `string` — Like <input accept>, e.g. "image/*,.pdf".
  - `multiple`: `boolean` = `true` — Allow several files.
  - `maxSize`: `number` — Reject files larger than this (bytes).
  - `disabled`: `boolean` — Disable browsing and dropping.
  - `title`: `React.ReactNode` = `"Drop files or browse"` — Headline.
  - `description`: `React.ReactNode` — Hint under the headline.
- **AttachmentProgressRing** (`data-slot="attachment-progress"`) — Standalone circular progress (currentColor) used by uploading attachments.

## Accessibility

- Image tiles render <img alt={name}>; chips render the name as text, so every file has a readable name.
- The remove button is a real <button> labelled “Remove <file name>” with a 28px hit area; it is revealed on hover and on keyboard focus within the item.
- Upload failures are announced once with role=alert; progress is not announced on every tick.
- The list is a <ul aria-label="Attachments">; the overflow button is labelled “Show N more attachments”.
- The dropzone is a native <button> that opens the file picker; the drop target never steals focus.
- Reduced motion: Items fade in and out without scale, blur or layout travel; the indeterminate ring pulses instead of spinning; hover lifts are removed.

| Keys | Action |
| --- | --- |
| Tab | Moves through each attachment's Retry and Remove buttons |
| Enter / Space | Activates Remove, Retry, the +N stack or the dropzone |

## Notes for agents

- Keep attachments in state as AttachmentItem[] and render <AttachmentList items={…} />; use createAttachment(file) to build items (it creates an object URL for images — revoke it with URL.revokeObjectURL when removing).
- Helpers exported alongside: formatBytes, attachmentKind, acceptsFile, filesFromDataTransfer, dragHasFiles.
- Progress is 0..1, not a percentage. Omit progress for an indeterminate ring.
- Inside a composer, prefer composer's built-in ComposerAttachments, which wires paste, drop and removal.

## Examples

### A single file (minimal)

```tsx
import { Attachment } from "@kura-ui/react/attachment";

export function AttachmentMinimal() {
  return <Attachment name="q3-board-report.pdf" type="application/pdf" size={2_480_000} />;
}
```

### Mixed states with overflow (full)

Thumbnails, a live upload, a failed upload with retry, remove buttons and a +N stack.

```tsx
"use client";

import * as React from "react";
import { AttachmentList } from "@kura-ui/react/attachment";
import { type AttachmentItem } from "@kura-ui/react/attachment";

const initial: AttachmentItem[] = [
  { id: "1", name: "brief.md", type: "text/markdown", size: 4_210 },
  { id: "2", name: "harbour.png", type: "image/png", size: 812_000, url: photo(205, 160) },
  {
    id: "3",
    name: "transactions.csv",
    type: "text/csv",
    size: 18_400_000,
    status: "uploading",
    progress: 0.18,
  },
  {
    id: "4",
    name: "schema.ts",
    type: "text/typescript",
    size: 9_800,
    status: "error",
    error: "Network connection lost",
  },
  { id: "5", name: "dunes.jpg", type: "image/jpeg", size: 1_200_000, url: photo(30, 25) },
  { id: "6", name: "interview.m4a", type: "audio/mp4", size: 6_300_000 },
  { id: "7", name: "notes.zip", type: "application/zip", size: 340_000 },
];

const photo = (a: number, b: number) =>
  `data:image/svg+xml;utf8,${encodeURIComponent(
    `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64"><defs><linearGradient id="g" x1="0" y1="0" x2="0" y2="1"><stop offset="0" stop-color="hsl(${a} 55% 78%)"/><stop offset="1" stop-color="hsl(${a + 20} 45% 90%)"/></linearGradient></defs><rect width="64" height="64" fill="url(#g)"/><circle cx="44" cy="20" r="7" fill="hsl(${b} 80% 92%)"/><path d="M0 46 L18 30 L32 42 L44 34 L64 50 V64 H0Z" fill="hsl(${b} 25% 38%)"/><path d="M0 54 L22 44 L40 52 L64 46 V64 H0Z" fill="hsl(${b} 20% 26%)"/></svg>`,
  )}`;

export function AttachmentFull() {
  const [items, setItems] = React.useState(initial);

  // Simulate an upload ticking forward.
  React.useEffect(() => {
    const id = setInterval(() => {
      setItems((list) =>
        list.map((item) => {
          if (item.status !== "uploading") return item;
          const progress = Math.min(1, (item.progress ?? 0) + 0.07 + Math.random() * 0.06);
          return progress >= 1
            ? { ...item, status: "ready", progress: undefined }
            : { ...item, progress };
        }),
      );
    }, 450);
    return () => clearInterval(id);
  }, []);

  return (
    <div className="flex w-full max-w-xl flex-col gap-3">
      <AttachmentList
        items={items}
        max={4}
        onRemove={(id) => setItems((list) => list.filter((i) => i.id !== id))}
        onRetry={(id) =>
          setItems((list) =>
            list.map((i) =>
              i.id === id ? { ...i, status: "uploading", progress: 0, error: undefined } : i,
            ),
          )
        }
      />
      <p className="text-kura-fg-subtle text-xs">
        Hover a file to remove it · Retry the failed upload · Open the +N stack
      </p>
    </div>
  );
}
```

### Dropzone feeding a list (composition)

Browse or drop files; accepted ones upload, rejected ones are reported.

```tsx
"use client";

import * as React from "react";
import { AttachmentDropzone, AttachmentList } from "@kura-ui/react/attachment";
import { type AttachmentItem, createAttachment } from "@kura-ui/react/attachment";

export function AttachmentWithDropzone() {
  const [items, setItems] = React.useState<AttachmentItem[]>([]);
  const [rejected, setRejected] = React.useState<string | null>(null);

  React.useEffect(() => {
    if (!items.some((i) => i.status === "uploading")) return;
    const id = setInterval(() => {
      setItems((list) =>
        list.map((i) => {
          if (i.status !== "uploading") return i;
          const progress = (i.progress ?? 0) + 0.2;
          return progress >= 1
            ? { ...i, status: "ready", progress: undefined }
            : { ...i, progress };
        }),
      );
    }, 300);
    return () => clearInterval(id);
  }, [items]);

  return (
    <div className="flex w-full max-w-md flex-col gap-3">
      <AttachmentDropzone
        accept="image/*,.pdf,.csv,.md,.txt"
        maxSize={10 * 1024 * 1024}
        description="Images, PDF, CSV or Markdown · up to 10 MB"
        onFiles={(files, bad) => {
          setRejected(bad.length ? `${bad.map((f) => f.name).join(", ")} not supported` : null);
          setItems((list) => [
            ...list,
            ...files.map((f) => createAttachment(f, { status: "uploading", progress: 0 })),
          ]);
        }}
      />
      {rejected && (
        <p role="alert" className="text-kura-danger-text text-xs">
          {rejected}
        </p>
      )}
      {items.length > 0 && (
        <AttachmentList
          items={items}
          onRemove={(id) =>
            setItems((list) => {
              const gone = list.find((i) => i.id === id);
              if (gone?.url?.startsWith("blob:")) URL.revokeObjectURL(gone.url);
              return list.filter((i) => i.id !== id);
            })
          }
        />
      )}
    </div>
  );
}
```

## Dependencies

- npm: `lucide-react`, `motion`
- Kura registry items: `kura-theme`, `kura-motion`, `use-reduced-motion`, `utils`
- Related: `composer`, `artifact-card`, `audio-waveform`

---

# Audio Waveform

> Canvas audio visualiser — live bars, mirrored history or oscilloscope line from a mic or media element, or recorded peaks with a seek scrubber.

- **Slug:** `audio-waveform` · **Category:** voice · **Status:** beta
- **Import:** `import { AudioWaveform } from "@kura-ui/react/audio-waveform";`
- **Docs:** https://kuro.abstergo.fyi/components/audio-waveform
- **Registry item:** https://kuro.abstergo.fyi/r/audio-waveform.json
- **Tags:** audio, waveform, visualizer, canvas, voice, microphone, spectrum, player

## Install

```bash
# shadcn registry (copies source into your project)
npx shadcn@latest add https://kuro.abstergo.fyi/r/audio-waveform.json
# Kura CLI (same, plus dependency resolution and --json output)
npx @kura-ui/cli add audio-waveform
# npm package
npm install @kura-ui/react
```

## When to use

- Show that the mic is live while dictating or talking to a voice agent (mirrored history).
- Visualise playback of a model's spoken reply or an <audio> element (spectrum bars or line).
- A recorded voice note / audio attachment with a played/unplayed split and drag-to-seek.

## When not to use

- A complete dictation control with permissions, transcript and states — use voice-dictation (it renders this).
- An ambient “the agent is speaking” blob — use agent-orb.
- A non-audio progress indicator — use a progress bar or context-meter.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `analyser` | `AudioAnalyser` | — | no | Live analyser from useAudioAnalyser. Share one between several visuals. |
| `source` | `MediaStream \| HTMLMediaElement \| null` | — | no | Mic stream or media element to analyse internally when no analyser is passed. |
| `simulate` | `boolean \| "speech" \| "music" \| "silence"` | — | no | Synthetic data for docs, previews and pre-permission states. |
| `peaks` | `readonly number[]` | — | no | Static mode: amplitudes 0..1 of any length (resampled to the bar count). Build them with peaksFromSamples(). |
| `progress` | `number` | — | no | Playback position 0..1 in static mode; bars after it are faded. |
| `onSeek` | `(progress: number) => void` | — | no | Turns the waveform into a seek slider (drag, click, arrow keys). Receives 0..1. |
| `duration` | `number` | — | no | Duration in seconds for the slider's spoken value (“0:12 of 1:04”). |
| `variant` | `"bars" \| "mirrored" \| "line"` | `"mirrored"` | no | bars = bottom-aligned, mirrored = symmetric around the centre line, line = oscilloscope (live) or filled envelope (static). |
| `display` | `"history" \| "spectrum"` | — | no | Live data for bars/mirrored: history scrolls recent loudness right→left, spectrum shows frequency bands. Default: history for mirrored, spectrum for bars. |
| `barWidth` | `number` | `3` | no | Bar width in CSS px. |
| `barGap` | `number` | `2` | no | Gap between bars in CSS px. |
| `minBarHeight` | `number` | `2` | no | Minimum bar height so silence reads as a dotted baseline. |
| `tone` | `"default" \| "muted" \| "accent"` | `"default"` | no | Colour from tokens: ink, subtle ink, or the jade signal (only for live AI listening — once per view). |
| `active` | `boolean` | `true` | no | Pause the live animation; the last frame stays on screen. |
| `label` | `string` | — | no | Accessible name. Default "Audio waveform", or "Seek" when onSeek is set. |

Native attributes of the root element, `className` and `ref` are passed through.

## Anatomy

- **AudioWaveform** (`data-slot="audio-waveform"`) — Root sized by CSS (default h-10 w-full). data-mode = live | static, data-variant, data-status (analyser status), data-scrubbing.

## Accessibility

- Role: `img (display) or slider (with onSeek)`
- Display-only waveforms are role=img with a label; the canvas itself is aria-hidden.
- With onSeek it is a focusable slider with aria-valuenow (0–100) and aria-valuetext (“0:12 of 1:04” when duration is set).
- Colours come from tokens via currentColor, so contrast follows light/dark themes automatically.
- Pair live waveforms with a text status (“Listening”, “Muted”) — the visual alone is not an accessible state.
- Reduced motion: Live data becomes a calm level meter redrawn ~6×/s without sub-frame scrolling; static waveforms are unaffected.

| Keys | Action |
| --- | --- |
| ArrowRight / ArrowUp | Seek forward 5% (Shift: 10%) |
| ArrowLeft / ArrowDown | Seek back 5% (Shift: 10%) |
| Home / End | Start / end |

## Notes for agents

- Size it with CSS (className="h-8 w-48"); the canvas tracks the element size and device pixel ratio automatically.
- For a mic: const rec = useMediaRecorder(); <AudioWaveform source={rec.stream} />. For playback pass the <audio> element as source.
- Pass one `analyser` to several visuals instead of creating an analyser per component.
- peaksFromSamples(audioBuffer.getChannelData(0), 200) turns decoded audio into peaks.
- Use tone="accent" only while the AI is actively listening, and only once per view.

## Examples

### Simulated live input (minimal)

```tsx
import { AudioWaveform } from "@kura-ui/react/audio-waveform";

export function AudioWaveformMinimal() {
  return (
    <div className="w-64">
      <AudioWaveform simulate />
    </div>
  );
}
```

### Player with scrub, and every variant (full)

Recorded peaks with play/pause, drag-to-seek and a timer; below, bars/spectrum, mirrored/history and line.

```tsx
"use client";

import { Pause, Play } from "lucide-react";
import * as React from "react";
import { IconButton } from "@kura-ui/react/icon-button";
import { AudioWaveform } from "@kura-ui/react/audio-waveform";

function demoPeaks(count: number, seed = 7): number[] {
  let s = seed;
  const rand = () => {
    s = (s * 16807) % 2147483647;
    return s / 2147483647;
  };
  return Array.from({ length: count }, (_, i) => {
    const phrase = Math.sin((i / count) * Math.PI * 5.3) * 0.5 + 0.5;
    const gap = i % 37 < 3 ? 0.08 : 1;
    return Math.min(1, (0.15 + 0.85 * phrase * (0.45 + rand() * 0.55)) * gap);
  });
}

const DURATION = 64;

export function AudioWaveformFull() {
  const peaks = React.useMemo(() => demoPeaks(220), []);
  const [progress, setProgress] = React.useState(0.32);
  const [playing, setPlaying] = React.useState(false);

  React.useEffect(() => {
    if (!playing) return;
    const id = setInterval(() => {
      setProgress((p) => {
        const next = p + 0.1 / DURATION;
        if (next >= 1) {
          setPlaying(false);
          return 1;
        }
        return next;
      });
    }, 100);
    return () => clearInterval(id);
  }, [playing]);

  const t = progress * DURATION;
  return (
    <div className="flex w-full max-w-lg flex-col gap-6">
      <div className="flex items-center gap-3 rounded-kura-xl bg-kura-surface p-2 pr-4 shadow-kura-sm">
        <IconButton
          label={playing ? "Pause" : "Play"}
          icon={playing ? <Pause className="fill-current" /> : <Play className="fill-current" />}
          variant="primary"
          size="md"
          className="rounded-full"
          tooltip={false}
          onClick={() => {
            if (progress >= 1) setProgress(0);
            setPlaying((p) => !p);
          }}
        />
        <AudioWaveform
          peaks={peaks}
          progress={progress}
          onSeek={setProgress}
          duration={DURATION}
          variant="mirrored"
          barWidth={2}
          barGap={2}
          minBarHeight={2}
          label="Seek recording"
          className="h-9 flex-1"
        />
        <span className="w-9 shrink-0 text-right text-kura-fg-muted text-xs tabular-nums">
          {Math.floor(t / 60)}:{String(Math.floor(t % 60)).padStart(2, "0")}
        </span>
      </div>
      <div className="grid grid-cols-3 gap-4">
        <figure className="flex flex-col gap-2">
          <AudioWaveform simulate="music" variant="bars" display="spectrum" className="h-12" />
          <figcaption className="text-center text-kura-fg-subtle text-xs">
            bars · spectrum
          </figcaption>
        </figure>
        <figure className="flex flex-col gap-2">
          <AudioWaveform simulate="speech" variant="mirrored" display="history" className="h-12" />
          <figcaption className="text-center text-kura-fg-subtle text-xs">
            mirrored · history
          </figcaption>
        </figure>
        <figure className="flex flex-col gap-2">
          <AudioWaveform simulate="speech" variant="line" tone="muted" className="h-12" />
          <figcaption className="text-center text-kura-fg-subtle text-xs">line</figcaption>
        </figure>
      </div>
    </div>
  );
}
```

### Voice note in a chat bubble (composition)

A compact muted waveform with an icon-button play control.

```tsx
"use client";

import { Play } from "lucide-react";
import * as React from "react";
import { IconButton } from "@kura-ui/react/icon-button";
import { AudioWaveform } from "@kura-ui/react/audio-waveform";

function demoPeaks(count: number, seed = 7): number[] {
  let s = seed;
  const rand = () => {
    s = (s * 16807) % 2147483647;
    return s / 2147483647;
  };
  return Array.from({ length: count }, (_, i) => {
    const phrase = Math.sin((i / count) * Math.PI * 5.3) * 0.5 + 0.5;
    const gap = i % 37 < 3 ? 0.08 : 1;
    return Math.min(1, (0.15 + 0.85 * phrase * (0.45 + rand() * 0.55)) * gap);
  });
}

export function AudioWaveformVoiceNote() {
  const peaks = React.useMemo(() => demoPeaks(48, 3), []);
  const [progress, setProgress] = React.useState(0);
  return (
    <div className="flex w-full max-w-sm flex-col items-end gap-2">
      <div className="flex w-64 items-center gap-2.5 rounded-kura-2xl rounded-br-kura-sm bg-kura-surface-sunken py-2 pr-3.5 pl-2 shadow-kura-xs">
        <IconButton
          label="Play voice note"
          icon={<Play className="fill-current" />}
          variant="secondary"
          size="sm"
          className="rounded-full"
          tooltip={false}
          onClick={() => setProgress((p) => (p >= 1 ? 0 : Math.min(1, p + 0.25)))}
        />
        <AudioWaveform
          peaks={peaks}
          progress={progress}
          onSeek={setProgress}
          duration={14}
          barWidth={2}
          barGap={2}
          tone="muted"
          label="Seek voice note"
          className="h-7 flex-1"
        />
        <span className="text-[11px] text-kura-fg-subtle tabular-nums">0:14</span>
      </div>
      <span className="pr-1 text-[11px] text-kura-fg-subtle">Voice note · transcribed</span>
    </div>
  );
}
```

## Dependencies

- npm: none
- Kura registry items: `kura-theme`, `kura-merge-refs`, `use-audio-analyser`, `use-reduced-motion`, `utils`
- Related: `voice-dictation`, `agent-orb`, `attachment`

---

# Aurora

> Soft northern-lights background: folding light curtains drawn in a shader with premultiplied alpha, so it glows on dark and washes on light.

- **Slug:** `aurora` · **Category:** effects · **Status:** beta
- **Import:** `import { Aurora } from "@kura-ui/react/aurora";`
- **Docs:** https://kuro.abstergo.fyi/components/aurora
- **Registry item:** https://kuro.abstergo.fyi/r/aurora.json
- **Tags:** aurora, northern-lights, background, webgl, shader, hero, night, ambient

## Install

```bash
# shadcn registry (copies source into your project)
npx shadcn@latest add https://kuro.abstergo.fyi/r/aurora.json
# Kura CLI (same, plus dependency resolution and --json output)
npx @kura-ui/cli add aurora
# npm package
npm install @kura-ui/react
```

## When to use

- A sign-in, landing or 'welcome back' screen that should feel calm and a little magical.
- A night-themed hero or a header band above an agent dashboard.
- A background that must sit on top of an existing surface colour (it is transparent where there is no light).

## When not to use

- A colourful blob background filling the whole area — use mesh-gradient.
- Showing that an agent is busy — use border-beam or thinking-indicator.
- A voice agent's presence — use agent-orb.
- Behind dense UI or long text: the curtains move; keep content short and centred.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `colors` | `"signal" \| "polar" \| "ember" \| "mist" \| readonly [string, string, string]` | `"signal"` | no | A preset, or three CSS colours `[lower edge, middle, upper fringe]`. signal uses the theme accent; polar is classic green-teal-blue. |
| `intensity` | `number` | `0.8` | no | Brightness of the curtains, 0–1. |
| `speed` | `number` | `1` | no | Animation speed multiplier. 0 renders a still frame. |
| `stars` | `boolean` | `true` | no | Twinkling stars behind the curtains. Only drawn when the background is dark. |
| `paused` | `boolean` | `false` | no | Freeze the animation on the current frame. |
| `maxDpr` | `number` | `1.5` | no | Device-pixel-ratio cap. |
| `children` | `React.ReactNode` | — | no | Content rendered on top, in normal flow. |

Native attributes of the root element, `className` and `ref` are passed through.

## Anatomy

- **Aurora** (`data-slot="aurora"`) — Root container (`relative isolate overflow-hidden`). Give it a size and a background colour. `data-state` = animating | still.
- **ShaderCanvas** (`data-slot="aurora-canvas"`) — Transparent WebGL layer behind the children (aria-hidden).
- **Fallback** (`data-slot="aurora-fallback"`) — Blurred CSS radial gradients shown when WebGL2 is unavailable.

## Accessibility

- Decorative and aria-hidden; children keep their semantics.
- The curtains sit mostly in the lower half; place text near the top or centre and check contrast in both themes.
- Reduced motion: Renders one still frame (no drift, no twinkle). Theme changes redraw it.

## Notes for agents

- The canvas is transparent: set a background on the root (`bg-kura-canvas`, `bg-kura-surface-sunken`) — the aurora is light added on top of it.
- Give the root a height (`h-72`, `min-h-96`, `aspect-video`).
- Lift children above the canvas automatically (they are in flow); lift them above a `<Grain />` overlay with `relative z-10`.
- On light themes the curtains render as a deeper watercolour wash; check both themes.

## Examples

### Aurora on the canvas colour (minimal)

Give it a size and a background; the signal preset follows the theme.

```tsx
import { Aurora } from "@kura-ui/react/aurora";

export function AuroraMinimal() {
  return <Aurora className="h-72 w-full rounded-kura-xl bg-kura-canvas shadow-kura-sm" />;
}
```

### Presets, intensity, stars (full)

Every preset, intensity, stars and pause.

```tsx
"use client";

import * as React from "react";
import { Button } from "@kura-ui/react/button";
import { Aurora, type AuroraPreset } from "@kura-ui/react/aurora";

const presets: AuroraPreset[] = ["signal", "polar", "ember", "mist"];

export function AuroraFull() {
  const [preset, setPreset] = React.useState<AuroraPreset>("polar");
  const [intensity, setIntensity] = React.useState(0.85);
  const [stars, setStars] = React.useState(true);
  const [paused, setPaused] = React.useState(false);
  return (
    <div className="flex w-full max-w-2xl flex-col gap-4">
      <Aurora
        colors={preset}
        intensity={intensity}
        stars={stars}
        paused={paused}
        className="aspect-[16/9] w-full rounded-kura-xl bg-kura-surface-sunken shadow-kura-md"
      />
      <div className="flex flex-wrap items-center gap-1.5">
        {presets.map((p) => (
          <Button
            key={p}
            size="sm"
            variant={p === preset ? "secondary" : "ghost"}
            aria-pressed={p === preset}
            onClick={() => setPreset(p)}
            className="capitalize"
          >
            {p}
          </Button>
        ))}
        <span className="ml-auto flex gap-1.5">
          <Button
            size="sm"
            variant="ghost"
            aria-pressed={stars}
            onClick={() => setStars((s) => !s)}
          >
            Stars {stars ? "on" : "off"}
          </Button>
          <Button size="sm" variant="ghost" onClick={() => setPaused((p) => !p)}>
            {paused ? "Play" : "Pause"}
          </Button>
        </span>
      </div>
      <label className="flex max-w-xs flex-col gap-1.5 text-kura-fg-muted text-xs">
        Intensity {intensity.toFixed(2)}
        <input
          type="range"
          min={0}
          max={1}
          step={0.05}
          value={intensity}
          onChange={(e) => setIntensity(Number(e.target.value))}
          className="accent-kura-accent"
        />
      </label>
    </div>
  );
}
```

### Sign-in hero (composition)

Headline and Buttons over the aurora, finished with Grain.

```tsx
import { Button } from "@kura-ui/react/button";
import { Grain } from "@kura-ui/react/grain";
import { Aurora } from "@kura-ui/react/aurora";

export function AuroraSignIn() {
  return (
    <Aurora
      intensity={0.7}
      className="flex min-h-96 w-full flex-col items-center justify-start gap-3 rounded-kura-2xl bg-kura-canvas px-6 pt-14 text-center shadow-kura-md"
    >
      <h2 className="relative z-10 text-balance font-medium text-3xl text-kura-fg tracking-tight">
        Your agents worked through the night.
      </h2>
      <p className="relative z-10 max-w-sm text-kura-fg-muted text-sm leading-relaxed">
        Sign in to review 14 finished tasks and 2 waiting for approval.
      </p>
      <div className="relative z-10 mt-2 flex gap-2">
        <Button>Sign in</Button>
        <Button variant="secondary">Create account</Button>
      </div>
      <Grain opacity={0.18} />
    </Aurora>
  );
}
```

## Dependencies

- npm: none
- Kura registry items: `kura-theme`, `kura-merge-refs`, `kura-shader-color`, `shader-canvas`, `use-reduced-motion`, `utils`
- Related: `mesh-gradient`, `grain`, `particle-field`, `shader-canvas`

---

# Border Beam

> Animated light beam that travels around its parent's border — a quiet “an agent is working in here” signal for composers, cards and panels.

- **Slug:** `border-beam` · **Category:** effects · **Status:** beta
- **Import:** `import { BorderBeam } from "@kura-ui/react/border-beam";`
- **Docs:** https://kuro.abstergo.fyi/components/border-beam
- **Registry item:** https://kuro.abstergo.fyi/r/border-beam.json
- **Tags:** border, beam, glow, loading, busy, agent, conic-gradient, css

## Install

```bash
# shadcn registry (copies source into your project)
npx shadcn@latest add https://kuro.abstergo.fyi/r/border-beam.json
# Kura CLI (same, plus dependency resolution and --json output)
npx @kura-ui/cli add border-beam
# npm package
npm install @kura-ui/react
```

## When to use

- A composer, card or panel whose content an agent is currently editing or generating.
- A running tool call or background task row that should read as live without a spinner.
- Highlighting the one container on screen that is waiting for or producing AI output.

## When not to use

- Small inline 'thinking' feedback — use thinking-indicator or shimmer-text.
- Filling a background with colour — use mesh-gradient or aurora.
- Focus or selection states — use the focus ring (shadow-kura-focus), not a beam.
- Several beams on one screen at once: it is a signal; more than one or two becomes noise.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `active` | `boolean` | `true` | no | Show the beam. Toggling fades it in/out over 480ms and pauses the animation while hidden — keep it mounted. |
| `duration` | `number` | `6` | no | Seconds per lap. |
| `size` | `number` | `0.25` | no | Beam length as a share of the lap, 0.05–0.9. |
| `width` | `number` | `1` | no | Ring thickness in px. |
| `colors` | `readonly string[]` | — | no | CSS colours from tail to head. Default: transparent → jade at 45% → jade → accent-text. Tokens and color-mix() work. |
| `glow` | `boolean` | `false` | no | Add a blurred copy of the beam for a soft glow (not clipped by the parent unless it has overflow-hidden). |
| `reverse` | `boolean` | `false` | no | Travel counter-clockwise. |
| `offset` | `number` | `0` | no | Starting position as a share of the lap, 0–1. Use 0.5 on a second beam to run two beams opposite each other. |

Native attributes of the root element, `className` and `ref` are passed through.

## Anatomy

- **BorderBeam** (`data-slot="border-beam"`) — Absolutely positioned overlay (`inset-0`, `rounded-[inherit]`, pointer-events none). `data-active` mirrors `active`.
- **Glow** (`data-slot="border-beam-glow"`) — Blurred wrapper around a thicker ring; only rendered with `glow`.
- **Ring** (`data-slot="border-beam-ring"`) — The masked conic gradient ring that carries the animation.

## Accessibility

- Purely decorative (aria-hidden). Pair it with real text — a role=status label such as “Editing 3 files…” — so the busy state is not conveyed by motion alone.
- It never intercepts pointer events, so the container stays fully interactive.
- Reduced motion: The beam stops travelling and becomes a static, softly tinted ring (head colour at 45%) so the container still reads as active.

## Notes for agents

- The parent must be `relative` (or otherwise positioned) and should carry the border radius; the beam uses `rounded-[inherit]`.
- Render it as the last child so it paints above the content edge; it does not take space.
- Pure CSS: no 'use client' needed. Styles are injected once via a React 19 hoisted <style>.
- Keep it mounted and flip `active` instead of conditionally rendering, so it fades rather than pops.
- On wide, short elements the beam speeds up along the short sides (it is an angle sweep); prefer size 0.2–0.35 there.

## Examples

### Card with a beam (minimal)

Drop it inside any relative, rounded element.

```tsx
import { BorderBeam } from "@kura-ui/react/border-beam";

export function BorderBeamMinimal() {
  return (
    <div className="relative w-full max-w-sm rounded-kura-xl bg-kura-surface p-5 text-sm shadow-kura-sm">
      <p className="font-medium text-kura-fg">Indexing workspace</p>
      <p className="text-kura-fg-muted">The beam marks a container the agent is working in.</p>
      <BorderBeam />
    </div>
  );
}
```

### Composer with two beams (full)

Glow, width, size, speed, a second opposite beam via offset, and toggling active.

```tsx
"use client";

import * as React from "react";
import { Button } from "@kura-ui/react/button";
import { BorderBeam } from "@kura-ui/react/border-beam";

export function BorderBeamFull() {
  const [active, setActive] = React.useState(true);
  const [glow, setGlow] = React.useState(true);
  const [fast, setFast] = React.useState(false);
  return (
    <div className="flex w-full max-w-md flex-col items-center gap-5">
      <div className="relative flex h-40 w-full flex-col justify-between rounded-kura-2xl bg-kura-surface p-4 shadow-kura-sm">
        <p className="text-kura-fg-muted text-sm">Ask the agent to change something…</p>
        <div className="flex items-center justify-between text-kura-fg-subtle text-xs">
          <span>{active ? "Agent is editing 3 files" : "Idle"}</span>
          <span className="font-kura-mono">⌘↵</span>
        </div>
        <BorderBeam active={active} glow={glow} duration={fast ? 3 : 7} size={0.3} width={1.5} />
        <BorderBeam active={active} duration={fast ? 3 : 7} size={0.18} offset={0.5} />
      </div>
      <div className="flex flex-wrap justify-center gap-1.5">
        <Button
          size="sm"
          variant="secondary"
          aria-pressed={active}
          onClick={() => setActive((v) => !v)}
        >
          {active ? "Stop" : "Start"}
        </Button>
        <Button size="sm" variant="ghost" aria-pressed={glow} onClick={() => setGlow((v) => !v)}>
          Glow {glow ? "on" : "off"}
        </Button>
        <Button size="sm" variant="ghost" aria-pressed={fast} onClick={() => setFast((v) => !v)}>
          {fast ? "3s lap" : "7s lap"}
        </Button>
      </div>
    </div>
  );
}
```

### Running task row (composition)

ShimmerText status, a Stop Button and a beam that fades out when stopped.

```tsx
"use client";

import { FileCode2, Square } from "lucide-react";
import * as React from "react";
import { Button } from "@kura-ui/react/button";
import { ShimmerText } from "@kura-ui/react/shimmer-text";
import { BorderBeam } from "@kura-ui/react/border-beam";

export function BorderBeamAgentTask() {
  const [running, setRunning] = React.useState(true);
  return (
    <div className="relative flex w-full max-w-md items-center gap-3 rounded-kura-lg bg-kura-surface p-3 shadow-kura-sm">
      <span className="flex size-9 shrink-0 items-center justify-center rounded-kura-md bg-kura-accent-subtle text-kura-accent-text">
        <FileCode2 className="size-4" />
      </span>
      <div className="min-w-0 flex-1 text-sm" role="status" aria-live="polite">
        <p className="truncate font-medium text-kura-fg">auth/session.ts</p>
        {running ? (
          <ShimmerText className="text-xs">Refactoring token refresh…</ShimmerText>
        ) : (
          <span className="text-kura-fg-muted text-xs">Stopped by you</span>
        )}
      </div>
      <Button size="sm" variant="secondary" onClick={() => setRunning((r) => !r)}>
        {running ? <Square className="size-3 fill-current" /> : null}
        {running ? "Stop" : "Resume"}
      </Button>
      <BorderBeam active={running} glow duration={5} />
    </div>
  );
}
```

## Dependencies

- npm: none
- Kura registry items: `kura-theme`, `utils`
- Related: `thinking-indicator`, `shimmer-text`, `composer`, `tool-call`, `mesh-gradient`

---

# Button

> The Kura button: six variants, four sizes, loading state, asChild, tactile press and a signal focus ring.

- **Slug:** `button` · **Category:** primitives · **Status:** stable
- **Import:** `import { Button, ButtonSize, ButtonVariant } from "@kura-ui/react/button";`
- **Docs:** https://kuro.abstergo.fyi/components/button
- **Registry item:** https://kuro.abstergo.fyi/r/button.json
- **Tags:** button, action, cta, submit, link, loading

## Install

```bash
# shadcn registry (copies source into your project)
npx shadcn@latest add https://kuro.abstergo.fyi/r/button.json
# Kura CLI (same, plus dependency resolution and --json output)
npx @kura-ui/cli add button
# npm package
npm install @kura-ui/react
```

## When to use

- Any clickable action: submit, confirm, cancel, open.
- Links that should look like buttons (use asChild with your router's Link).

## When not to use

- Icon-only actions — use icon-button (it enforces an accessible label and adds a tooltip).
- Approve/deny decisions for agent actions — use approval-prompt.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `variant` | `"primary" \| "secondary" \| "ghost" \| "outline" \| "accent" \| "danger"` | `"primary"` | no | primary = ink call to action; accent = the AI signal color (max one per view); danger = destructive. |
| `size` | `"xs" \| "sm" \| "md" \| "lg"` | `"md"` | no | Height 24 / 28 / 32 / 40px. |
| `loading` | `boolean` | `false` | no | Shows a spinner, sets aria-busy and disables the button while keeping its width. |
| `asChild` | `boolean` | `false` | no | Render the single child element (e.g. <a> or <Link>) with button styles. |

Native attributes of the root element, `className` and `ref` are passed through.

## Anatomy

- **buttonVariants** — Function returning the class string, for non-button elements.

## Accessibility

- Defaults to type="button" so it never submits forms by accident; pass type="submit" explicitly.
- Disabled and loading buttons use the native disabled attribute.
- Focus ring: 1px canvas gap + 2px signal ring, only on :focus-visible.
- Reduced motion: The 0.97 press scale is disabled; color transitions remain.

| Keys | Action |
| --- | --- |
| Enter / Space | Activate |
| Tab | Move focus |

## Notes for agents

- Use `accent` only for the single most AI-specific action in view (e.g. “Run agent”). Default to `primary`.
- Icons inside are auto-sized; do not add size classes unless you need a non-default size.

## Examples

### Primary (minimal)

```tsx
import { Button } from "@kura-ui/react/button";

export function ButtonMinimal() {
  return <Button>Continue</Button>;
}
```

### Variants, sizes, loading (full)

```tsx
import { Sparkles, Trash2 } from "lucide-react";
import { Button } from "@kura-ui/react/button";

export function ButtonFull() {
  return (
    <div className="flex flex-col items-center gap-4">
      <div className="flex flex-wrap items-center justify-center gap-2">
        <Button variant="primary">Primary</Button>
        <Button variant="secondary">Secondary</Button>
        <Button variant="outline">Outline</Button>
        <Button variant="ghost">Ghost</Button>
        <Button variant="accent">
          <Sparkles /> Run agent
        </Button>
        <Button variant="danger">
          <Trash2 /> Delete
        </Button>
      </div>
      <div className="flex flex-wrap items-center justify-center gap-2">
        <Button size="xs" variant="secondary">
          XS
        </Button>
        <Button size="sm" variant="secondary">
          Small
        </Button>
        <Button size="md" variant="secondary">
          Medium
        </Button>
        <Button size="lg" variant="secondary">
          Large
        </Button>
        <Button loading>Saving</Button>
        <Button disabled variant="secondary">
          Disabled
        </Button>
      </div>
    </div>
  );
}
```

### As a link (asChild) (composition)

```tsx
import { ArrowUpRight } from "lucide-react";
import { Button } from "@kura-ui/react/button";

export function ButtonAsLink() {
  return (
    <Button asChild variant="outline">
      <a href="https://github.com/Absterrg0/Kura-UI">
        View source <ArrowUpRight />
      </a>
    </Button>
  );
}
```

## Dependencies

- npm: `radix-ui`
- Kura registry items: `kura-theme`, `spinner`, `utils`
- Related: `icon-button`, `kbd-shortcut`, `tooltip`

---

# Citation

> Inline numbered citation pill that links to its source and previews favicon, title, domain and snippet on hover/focus, plus a Sources strip or list.

- **Slug:** `citation` · **Category:** conversation · **Status:** beta
- **Import:** `import { Citation, CitationCard, CitationSource, Sources } from "@kura-ui/react/citation";`
- **Docs:** https://kuro.abstergo.fyi/components/citation
- **Registry item:** https://kuro.abstergo.fyi/r/citation.json
- **Tags:** citation, sources, rag, references, footnote, hover-card, search, attribution

## Install

```bash
# shadcn registry (copies source into your project)
npx shadcn@latest add https://kuro.abstergo.fyi/r/citation.json
# Kura CLI (same, plus dependency resolution and --json output)
npx @kura-ui/cli add citation
# npm package
npm install @kura-ui/react
```

## When to use

- Attribute sentences of a model's answer to retrieved sources (RAG, web search, file search) with inline [1] [2] pills.
- Preview a source without leaving the answer: hover or keyboard-focus the pill to see title, domain and the snippet used.
- List all sources behind an answer under it, as a compact chip strip or a numbered list (`Sources`).

## When not to use

- Plain links in prose with no source metadata — use an <a>.
- Footnotes in long-form documents that must print — use real footnotes.
- Showing the search tool call itself (query, results JSON) — use tool-call.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `index` | `number` | — | yes | 1-based citation number shown in the pill and the card corner. |
| `source` | `CitationSource` | — | yes | { title, url, snippet?, favicon?, siteName?, date? }. The domain is derived from `url`; without `favicon` a monogram tile is shown (no third-party favicon service is called). |
| `display` | `"number" \| "domain"` | `"number"` | no | Pill shows the number, or a favicon + site name (Perplexity style). |
| `openDelay` | `number` | `250` | no | Hover delay in ms before the preview opens (keyboard focus opens immediately). |
| `open` | `boolean` | — | no | Preview open (controlled). |
| `onOpenChange` | `(open: boolean) => void` | — | no | Called when the preview opens or closes. |

Native attributes of the root element, `className` and `ref` are passed through.

## Anatomy

- **Citation** (`data-slot="citation"`) — The pill: a real <a target="_blank"> to the source, `data-state="open" | "closed"`. Sized in em so it scales with the surrounding text.
- **Preview** (`data-slot="citation-preview"`) — The hover card (Kura Popover content, origin-aware pop-in, opens above the pill).
- **CitationCard** (`data-slot="citation-card"`) — Preview body: favicon, site · date, index, title link with an ↗ nudge, 3-line snippet. Reusable on its own.
  - `source`: `CitationSource` — Source to show.
  - `index`: `number` — Number shown in the corner.
- **Favicon** (`data-slot="citation-favicon"`) — 16px favicon or monogram tile (aria-hidden).
- **Sources** (`data-slot="citation-sources"`) — Sources behind an answer. `data-variant`.
  - `sources`: `readonly CitationSource[]` — In citation order (index = position + 1).
  - `variant`: `"strip" | "list"` = `"strip"` — strip = horizontally scrolling chips; list = numbered rows with snippets.
  - `label`: `React.ReactNode` = `"Sources"` — Heading (with a count). null hides it.
- **Source** (`data-slot="citation-source"`) — One <li> in Sources.

## Accessibility

- Each pill is a link named “Source 2: <title> (<domain>)”, so it makes sense out of context and in a links list.
- The preview opens on hover (with delay) and on keyboard focus, without moving focus; Escape or blur closes it. It never contains information that is not also reachable by following the link.
- Sources is an ordered list labelled by its heading.
- Links open in a new tab (`target="_blank" rel="noreferrer"`).
- Reduced motion: The preview only fades (no scale/translate) and the ↗ nudge on hover is removed.

| Keys | Action |
| --- | --- |
| Tab | Focus a pill — its preview opens |
| Enter | Open the source in a new tab |
| Escape | Close the preview |

## Notes for agents

- Place the pill directly after the punctuation-free end of the claim, inside the same text node's parent (it is inline and em-sized).
- Reuse the same index for repeated citations of the same source; Sources numbering is by array position.
- Pass favicons you already have (e.g. from your search API); the component never fetches favicons itself.
- Import Sources from the same entry: `import { Citation, Sources } from "@kura-ui/react/citation"`.

## Examples

### One citation (minimal)

A numbered pill at the end of a sentence.

```tsx
import { Citation, type CitationSource } from "@kura-ui/react/citation";

const SOURCES: CitationSource[] = [
  {
    title: "useOptimistic – React",
    url: "https://react.dev/reference/react/useOptimistic",
    siteName: "React",
    snippet:
      "useOptimistic is a React Hook that lets you optimistically update the UI while an async action is underway.",
  },
  {
    title: "Server Actions and Mutations",
    url: "https://nextjs.org/docs/app/building-your-application/data-fetching/server-actions-and-mutations",
    siteName: "Next.js",
    date: "Jun 2026",
    snippet:
      "Server Actions are asynchronous functions that are executed on the server. They can be called in Server and Client Components to handle form submissions and data mutations.",
  },
  {
    title: "Optimistic UI patterns, revisited",
    url: "https://www.example.com/blog/optimistic-ui",
    snippet:
      "The trick is not the optimism itself but the rollback: show the failure where the user is looking, and restore the previous value without a jump.",
  },
];

export function CitationMinimal() {
  return (
    <p className="max-w-md text-[15px] text-kura-fg leading-relaxed">
      React exposes a dedicated hook for optimistic updates
      <Citation index={1} source={SOURCES[0]!} />.
    </p>
  );
}
```

### Citations with a sources strip (full)

Number and domain pills, a custom open delay, and the Sources strip below.

```tsx
import { Citation, type CitationSource, Sources } from "@kura-ui/react/citation";

const SOURCES: CitationSource[] = [
  {
    title: "useOptimistic – React",
    url: "https://react.dev/reference/react/useOptimistic",
    siteName: "React",
    snippet:
      "useOptimistic is a React Hook that lets you optimistically update the UI while an async action is underway.",
  },
  {
    title: "Server Actions and Mutations",
    url: "https://nextjs.org/docs/app/building-your-application/data-fetching/server-actions-and-mutations",
    siteName: "Next.js",
    date: "Jun 2026",
    snippet:
      "Server Actions are asynchronous functions that are executed on the server. They can be called in Server and Client Components to handle form submissions and data mutations.",
  },
  {
    title: "Optimistic UI patterns, revisited",
    url: "https://www.example.com/blog/optimistic-ui",
    snippet:
      "The trick is not the optimism itself but the rollback: show the failure where the user is looking, and restore the previous value without a jump.",
  },
];

export function CitationFull() {
  return (
    <div className="flex w-full max-w-lg flex-col gap-5">
      <p className="text-[15px] text-kura-fg leading-relaxed">
        Render the new count immediately with{" "}
        <code className="font-kura-mono text-sm">useOptimistic</code>
        <Citation index={1} source={SOURCES[0]!} openDelay={150} />, run the mutation in a Server
        Action
        <Citation index={2} source={SOURCES[1]!} display="domain" />, and restore the previous value
        quietly if it fails
        <Citation index={3} source={SOURCES[2]!} />.
      </p>
      <Sources sources={SOURCES} variant="strip" />
    </div>
  );
}
```

### Sources list (variant)

Numbered rows with site, date and snippet.

```tsx
import { type CitationSource, Sources } from "@kura-ui/react/citation";

const SOURCES: CitationSource[] = [
  {
    title: "useOptimistic – React",
    url: "https://react.dev/reference/react/useOptimistic",
    siteName: "React",
    snippet:
      "useOptimistic is a React Hook that lets you optimistically update the UI while an async action is underway.",
  },
  {
    title: "Server Actions and Mutations",
    url: "https://nextjs.org/docs/app/building-your-application/data-fetching/server-actions-and-mutations",
    siteName: "Next.js",
    date: "Jun 2026",
    snippet:
      "Server Actions are asynchronous functions that are executed on the server. They can be called in Server and Client Components to handle form submissions and data mutations.",
  },
  {
    title: "Optimistic UI patterns, revisited",
    url: "https://www.example.com/blog/optimistic-ui",
    snippet:
      "The trick is not the optimism itself but the rollback: show the failure where the user is looking, and restore the previous value without a jump.",
  },
];

export function CitationSourcesList() {
  return (
    <Sources sources={SOURCES} variant="list" label="Further reading" className="w-full max-w-lg" />
  );
}
```

### In an assistant message (composition)

Pills inside a Message with a label-less strip.

```tsx
import { Message, MessageAvatar } from "@kura-ui/react/message";
import { Citation, type CitationSource, Sources } from "@kura-ui/react/citation";

const SOURCES: CitationSource[] = [
  {
    title: "useOptimistic – React",
    url: "https://react.dev/reference/react/useOptimistic",
    siteName: "React",
    snippet:
      "useOptimistic is a React Hook that lets you optimistically update the UI while an async action is underway.",
  },
  {
    title: "Server Actions and Mutations",
    url: "https://nextjs.org/docs/app/building-your-application/data-fetching/server-actions-and-mutations",
    siteName: "Next.js",
    date: "Jun 2026",
    snippet:
      "Server Actions are asynchronous functions that are executed on the server. They can be called in Server and Client Components to handle form submissions and data mutations.",
  },
  {
    title: "Optimistic UI patterns, revisited",
    url: "https://www.example.com/blog/optimistic-ui",
    snippet:
      "The trick is not the optimism itself but the rollback: show the failure where the user is looking, and restore the previous value without a jump.",
  },
];

export function CitationInMessage() {
  return (
    <Message
      from="assistant"
      name="Kura"
      avatar={<MessageAvatar name="Kura" />}
      className="max-w-xl"
    >
      <p>
        Yes — React 19 ships <code>useOptimistic</code> for exactly this
        <Citation index={1} source={SOURCES[0]!} />. Pair it with a Server Action so the request and
        the rollback live in one place
        <Citation index={2} source={SOURCES[1]!} />.
      </p>
      <Sources sources={SOURCES.slice(0, 2)} label={null} />
    </Message>
  );
}
```

## Dependencies

- npm: `lucide-react`
- Kura registry items: `kura-theme`, `popover`, `use-controllable-state`, `utils`
- Related: `message`, `streaming-text`, `tool-call`

---

# Code Block

> Syntax-highlighted code with a filename header, copy, line numbers, highlighted lines, diffs, wrap, collapsible height and streaming-safe rendering.

- **Slug:** `code-block` · **Category:** conversation · **Status:** beta
- **Import:** `import { CodeBlock, CodeToken, CodeTokenType } from "@kura-ui/react/code-block";`
- **Docs:** https://kuro.abstergo.fyi/components/code-block
- **Registry item:** https://kuro.abstergo.fyi/r/code-block.json
- **Tags:** code, syntax-highlighting, diff, copy, streaming, snippet, pre, markdown

## Install

```bash
# shadcn registry (copies source into your project)
npx shadcn@latest add https://kuro.abstergo.fyi/r/code-block.json
# Kura CLI (same, plus dependency resolution and --json output)
npx @kura-ui/cli add code-block
# npm package
npm install @kura-ui/react
```

## When to use

- Show code a model wrote in a chat answer, including while it is still streaming.
- Show a file or snippet with a filename header and a copy button (docs, READMEs, agent output).
- Show an agent's proposed edit as a unified diff with +/- lines.
- Long files that should start collapsed to a fixed height with a “Show N more lines” control.
- Terminal commands (language="bash") with an extra header action such as Run.

## When not to use

- Inline code inside a sentence — use a plain <code> element.
- Tool arguments/results JSON inside an agent step — use tool-call, which pretty-prints JSON for you.
- Prose output from a model — use streaming-text or message.
- Editable code — use a real editor (CodeMirror/Monaco); CodeBlock is read-only.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `code` | `string` | — | yes | The source to display. For diffs pass unified-diff lines prefixed with `+`, `-` or a space (`@@`, `+++`, `---` lines render as meta). |
| `language` | `string` | `"text"` | no | Language id: ts/tsx/js/jsx, json, bash/sh, python, css, html/xml, yaml, sql, go, rust, java, … (see `supportedLanguages`). Unknown ids render as plain text. |
| `filename` | `string` | — | no | File name shown in the header, e.g. "app/page.tsx". |
| `lineNumbers` | `boolean` | `false` | no | Show a tabular line-number gutter (not selectable, aria-hidden). |
| `highlightLines` | `readonly number[]` | — | no | 1-based line numbers to emphasise with a tinted row and a left rule. |
| `diff` | `boolean` | — | no | Render `+`/`-` prefixed lines as additions/removals (green/red row, sign gutter, screen-reader “added:/removed:”). Defaults to true when `language` is "diff"; otherwise the content after the sign is highlighted with `language`. |
| `streaming` | `boolean` | `false` | no | Code is still arriving. Only complete lines are tokenized (memoized), the unfinished last line renders plain until its newline lands, and a block caret marks the live edge — no flicker from half-open strings or comments. |
| `wrap` | `boolean` | — | no | Soft-wrap long lines (controlled). |
| `defaultWrap` | `boolean` | `false` | no | Initial wrap state when uncontrolled. |
| `onWrapChange` | `(wrap: boolean) => void` | — | no | Called when the wrap toggle is pressed. |
| `maxHeight` | `number` | — | no | Collapse code taller than this many px, with a bottom fade and a “Show N more lines” pill; the header gets an expand/collapse button. |
| `expanded` | `boolean` | — | no | Expanded past `maxHeight` (controlled). |
| `defaultExpanded` | `boolean` | `false` | no | Initial expanded state when uncontrolled. |
| `onExpandedChange` | `(expanded: boolean) => void` | — | no | Called when the code is expanded or collapsed. |
| `copyable` | `boolean` | `true` | no | Show the copy button (icon cross-fades to a check for 1.6s on success). |
| `onCopy` | `(code: string) => void` | — | no | Called with the copied text after a successful copy. |
| `header` | `boolean` | `true` | no | Show the header row (filename/language and actions). Without it, no wrap or copy button is shown. |
| `actions` | `React.ReactNode` | — | no | Extra header actions rendered before wrap/copy, e.g. a ghost xs Button “Run” or “Apply”. |

Native attributes of the root element, `className` and `ref` are passed through.

## Anatomy

- **CodeBlock** (`data-slot="code-block"`) — Root. `data-language`, `data-wrap`, `data-streaming`, `data-state="collapsed" | "expanded"` (only when collapsible).
- **Header** (`data-slot="code-block-header"`) — Filename/language and actions.
- **Title** (`data-slot="code-block-title"`) — Filename, or the language when no filename is given.
- **Language** (`data-slot="code-block-language"`) — Language badge, shown next to a filename.
- **Body** (`data-slot="code-block-body"`) — Height-limited wrapper (transitions max-height when expanding).
- **Code** (`data-slot="code-block-code"`) — The <code> element holding the lines.
- **Line** (`data-slot="code-block-line"`) — `data-line`, `data-highlighted`, `data-diff="add" | "remove" | "context" | "meta"`.
- **LineNumber** (`data-slot="code-block-line-number"`) — Gutter number (aria-hidden).
- **Caret** (`data-slot="code-block-caret"`) — Streaming caret (aria-hidden).
- **Expand** (`data-slot="code-block-expand"`) — Bottom fade + “Show N more lines” pill while collapsed.

## Accessibility

- Role: `region`
- The scroll area is a focusable `role="region"` labelled “<filename or language> code”, so keyboard users can scroll wide code with the arrow keys.
- Copy, wrap and expand are labelled icon buttons with tooltips; wrap exposes `aria-pressed`, expand exposes `aria-expanded`.
- A polite status region announces “Copied to clipboard”.
- Line numbers, diff signs and the caret are aria-hidden; removed/added lines get visually hidden “removed:”/“added:” prefixes.
- Syntax colours derive from --kura-fg-muted, keeping its ≥ 4.5:1 contrast in both themes.
- Reduced motion: The copy icon swap becomes a pure cross-fade (no scale/blur), the streaming caret stops pulsing and expanding is instant.

| Keys | Action |
| --- | --- |
| Tab | Moves through header actions, then the scrollable code region |
| ← / → | Scrolls wide code horizontally when the region is focused |
| Enter / Space | Activates copy, wrap or expand |

## Notes for agents

- Highlighting is built in, synchronous and dependency-free (no shiki/prism needed); unknown languages render as plain text.
- While a model is still writing code, pass `streaming` and the growing string as `code`; set it to false when the fence closes.
- For diffs keep the leading `+`/`-`/space on every line and set `diff` (or language="diff" for no inner highlighting).
- Theme the palette with CSS variables on any ancestor: --kura-syntax-keyword, -string, -constant, -function, -type, -tag, -attr, -property.
- `highlightCode(code, language)` is exported for custom renderers; it returns tokens grouped by line.

## Examples

### Snippet (minimal)

Code + language. Header shows the language; copy and wrap are built in.

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

const SNIPPET = `import { StreamingText } from "@kura-ui/react/streaming-text";

export function Answer({ stream }: { stream: AsyncIterable<string> }) {
  // Bursty tokens are evened out into a calm cadence.
  return <StreamingText stream={stream} speed={90} className="max-w-prose" />;
}`;

export function CodeBlockMinimal() {
  return <CodeBlock code={SNIPPET} language="tsx" className="w-full max-w-xl" />;
}
```

### File with every option (full)

Filename, line numbers, highlighted lines, controlled wrap, collapsed to 300px, onCopy.

```tsx
"use client";

import * as React from "react";
import { CodeBlock } from "@kura-ui/react/code-block";

const ROUTE = `import { anthropic } from "@ai-sdk/anthropic";
import { streamText } from "ai";

export const maxDuration = 30;

export async function POST(req: Request) {
  const { messages } = await req.json();

  const result = streamText({
    model: anthropic("claude-opus-5-5"),
    system: "You are a calm, precise assistant.",
    messages,
    temperature: 0.4,
  });

  return result.toUIMessageStreamResponse();
}

// Tokens arrive in bursts; the client smooths them with <StreamingText />.
export const runtime = "edge";
const RETRIES = 3;
const TIMEOUT_MS = 12_000;`;

export function CodeBlockFull() {
  const [wrap, setWrap] = React.useState(false);
  const [copies, setCopies] = React.useState(0);
  return (
    <div className="flex w-full max-w-xl flex-col gap-2">
      <CodeBlock
        code={ROUTE}
        language="ts"
        filename="app/api/chat/route.ts"
        lineNumbers
        highlightLines={[9, 10, 11, 12, 13, 14]}
        wrap={wrap}
        onWrapChange={setWrap}
        maxHeight={300}
        defaultExpanded={false}
        copyable
        onCopy={() => setCopies((c) => c + 1)}
        header
      />
      <p className="font-kura-mono text-kura-fg-subtle text-xs tabular-nums">
        wrap: {String(wrap)} · copied {copies}×
      </p>
    </div>
  );
}
```

### Diff (variant)

A proposed edit as a unified diff, highlighted as TSX.

```tsx
"use client";

import * as React from "react";
import { CodeBlock } from "@kura-ui/react/code-block";

const DIFF = `@@ -4,7 +4,8 @@ export function Answer() {
   const [open, setOpen] = React.useState(false);
-  const items = data.filter((d) => d.visible);
+  const items = React.useMemo(() => data.filter((d) => d.visible), [data]);
+  const reduced = useReducedMotion();
   return (
-    <List items={items} animate />
+    <List items={items} animate={!reduced} />
   );`;

export function CodeBlockDiff() {
  return (
    <CodeBlock
      code={DIFF}
      language="tsx"
      diff
      filename="components/answer.tsx"
      lineNumbers
      className="w-full max-w-xl"
    />
  );
}
```

### Streaming (state)

Code arriving a few characters at a time — the open last line never flickers.

```tsx
"use client";

import { RotateCcw } from "lucide-react";
import * as React from "react";
import { Button } from "@kura-ui/react/button";
import { CodeBlock } from "@kura-ui/react/code-block";

const SNIPPET = `import { StreamingText } from "@kura-ui/react/streaming-text";

export function Answer({ stream }: { stream: AsyncIterable<string> }) {
  // Bursty tokens are evened out into a calm cadence.
  return <StreamingText stream={stream} speed={90} className="max-w-prose" />;
}`;

export function CodeBlockStreaming() {
  const [run, setRun] = React.useState(0);
  const [length, setLength] = React.useState(0);
  // biome-ignore lint/correctness/useExhaustiveDependencies: `run` restarts the fake stream
  React.useEffect(() => {
    setLength(0);
    let n = 0;
    const id = setInterval(() => {
      n = Math.min(SNIPPET.length, n + 2 + Math.floor(Math.random() * 7));
      setLength(n);
      if (n >= SNIPPET.length) clearInterval(id);
    }, 45);
    return () => clearInterval(id);
  }, [run]);
  const done = length >= SNIPPET.length;
  return (
    <div className="flex w-full max-w-xl flex-col items-end gap-2">
      <CodeBlock
        code={SNIPPET.slice(0, length)}
        language="tsx"
        filename="answer.tsx"
        streaming={!done}
        lineNumbers
        className="w-full"
      />
      <Button variant="secondary" size="sm" onClick={() => setRun((r) => r + 1)}>
        <RotateCcw /> Replay
      </Button>
    </div>
  );
}
```

### Command with a Run action (composition)

A bash block with a header Button, followed by a header-less output block.

```tsx
"use client";

import { Play } from "lucide-react";
import * as React from "react";
import { Button } from "@kura-ui/react/button";
import { CodeBlock } from "@kura-ui/react/code-block";

export function CodeBlockComposition() {
  const [ran, setRan] = React.useState(false);
  return (
    <div className="flex w-full max-w-xl flex-col gap-2">
      <CodeBlock
        code={"pnpm dlx @kura-ui/cli add code-block\npnpm --filter web dev --port 3000"}
        language="bash"
        actions={
          <Button variant="ghost" size="xs" onClick={() => setRan(true)}>
            <Play /> Run
          </Button>
        }
      />
      {ran && (
        <CodeBlock
          code={"✓ added code-block (4 files)\n▲ ready on http://localhost:3000"}
          header={false}
          copyable={false}
          className="animate-kura-rise-in"
        />
      )}
    </div>
  );
}
```

## Dependencies

- npm: `lucide-react`
- Kura registry items: `kura-theme`, `icon-button`, `use-controllable-state`, `utils`
- Related: `tool-call`, `message`, `streaming-text`, `approval-prompt`

---

# Command Palette

> ⌘K command palette for agent actions: fuzzy search, groups, recents, nested pages with async loading, and shortcut hints.

- **Slug:** `command-palette` · **Category:** input · **Status:** beta
- **Import:** `import { CommandPalette, CommandPaletteItem, CommandPaletteTrigger } from "@kura-ui/react/command-palette";`
- **Docs:** https://kuro.abstergo.fyi/components/command-palette
- **Registry item:** https://kuro.abstergo.fyi/r/command-palette.json
- **Tags:** command-palette, cmdk, search, launcher, keyboard, actions, menu, agent

## Install

```bash
# shadcn registry (copies source into your project)
npx shadcn@latest add https://kuro.abstergo.fyi/r/command-palette.json
# Kura CLI (same, plus dependency resolution and --json output)
npx @kura-ui/cli add command-palette
# npm package
npm install @kura-ui/react
```

## When to use

- A global launcher for agent actions: run/stop an agent, switch agents, add context, change settings.
- Navigating many commands or entities (files, threads, workflows) by typing.
- Multi-step choices as nested pages (“Change theme…” → Light / Dark), including lists fetched on demand.

## When not to use

- Commands typed inline inside a prompt — use slash-command-menu.
- Choosing a model — use model-picker.
- A handful of starter prompts in an empty chat — use prompt-suggestions.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `items` | `readonly CommandPaletteItem[]` | — | yes | Items: { id, label, description?, icon?, group?, keywords?, shortcut?, onSelect?, children?, loadChildren?, placeholder?, disabled? }. children/loadChildren open a nested page. |
| `open` | `boolean` | — | no | Controlled open state. |
| `defaultOpen` | `boolean` | `false` | no | Initial open state. |
| `onOpenChange` | `(open: boolean) => void` | — | no | Open state changes. |
| `hotkey` | `readonly KeyName[] \| null` | `["mod", "k"]` | no | Global toggle shortcut (works in inputs). null disables it. |
| `trigger` | `React.ReactElement` | — | no | Element rendered as the dialog trigger, e.g. <CommandPaletteTrigger />. |
| `recent` | `string[]` | — | no | Controlled recent item ids (most recent first), shown as “Recent” when the query is empty. |
| `defaultRecent` | `string[]` | — | no | Initial recents when uncontrolled. |
| `onRecentChange` | `(ids: string[]) => void` | — | no | Called when an item is used (persist it to localStorage if you like). |
| `recentLimit` | `number` | `4` | no | Max recents shown. |
| `onSelect` | `(item: CommandPaletteItem) => void` | — | no | Called after any leaf item runs (in addition to item.onSelect). |
| `onQueryChange` | `(query: string) => void` | — | no | Every query change — fetch server results into `items` and toggle `loading`. |
| `loading` | `boolean` | `false` | no | Show skeleton rows and aria-busy (root page). Nested pages with loadChildren handle this themselves. |
| `placeholder` | `string` | `"Search or run a command…"` | no | Search placeholder on the root page. |
| `emptyMessage` | `string` | `"No results"` | no | Shown when nothing matches. |
| `label` | `string` | `"Command palette"` | no | Accessible dialog title (visually hidden). |

Native attributes of the root element, `className` and `ref` are passed through.

## Anatomy

- **CommandPalette** (`data-slot="command-palette"`) — Modal dialog surface (translucent overlay, origin-top pop). data-page = current nested page id.
- **CommandPaletteSearch** (`data-slot="command-palette-search"`) — Search row with breadcrumbs for nested pages.
- **CommandPaletteGroup** (`data-slot="command-palette-group"`) — Group heading (Recent first).
- **CommandPaletteItem** (`data-slot="command-palette-item"`) — role=option row: icon, label, description, shortcut or chevron. data-active, data-disabled.
- **CommandPaletteLoading** (`data-slot="command-palette-loading"`) — Skeleton rows while loading.
- **CommandPaletteFooter** (`data-slot="command-palette-footer"`) — Result count and the Enter action (Run / Open).
- **CommandPaletteTrigger** (`data-slot="command-palette-trigger"`) — Search-field-styled button with the shortcut; pass it as `trigger`.
  - `placeholder`: `string` = `"Search or ask…"` — Button text.
  - `shortcut`: `readonly KeyName[]` = `["mod", "k"]` — Shortcut keys shown on the right.

## Accessibility

- Role: `dialog > combobox + listbox`
- A modal Radix dialog with a visually hidden title; focus moves to the search input on open and returns to the trigger on close.
- The input is a combobox using aria-activedescendant, so screen readers read the highlighted option while focus stays in the field.
- The listbox is aria-busy while loading; the footer's result count is a polite live region.
- Nested pages are announced through the input's label (“Search Change theme…”) and shown as breadcrumbs.
- Reduced motion: The dialog and overlay fade without scale; skeleton rows stop pulsing.

| Keys | Action |
| --- | --- |
| Mod+K | Toggle the palette (configurable) |
| ArrowDown / ArrowUp | Move the highlight (wraps, skips disabled) |
| Home / End | First / last item (empty query) |
| Enter | Run the item or open its page |
| Backspace (empty query) / Escape | Go back one page |
| Escape (root page) | Close |

## Notes for agents

- Mount one palette near the app root; it portals itself. Only one instance should bind ⌘K — pass hotkey={null} to others.
- Use `children` for static sub-pages and `loadChildren` for fetched ones (the loading state is automatic).
- Persist recents with recent/onRecentChange (e.g. localStorage); recents resolve ids anywhere in the item tree.
- Shortcuts on items are display-only; bind them with useHotkey so they also work when the palette is closed.
- scoreCommand(text, query) is exported if you need the same fuzzy ranking elsewhere.

## Examples

### With a trigger (minimal)

```tsx
import { FileSearch, MessageSquarePlus, Rocket } from "lucide-react";
import { CommandPalette, CommandPaletteTrigger } from "@kura-ui/react/command-palette";

const files = [
  "src/app/page.tsx",
  "src/app/layout.tsx",
  "src/lib/auth.ts",
  "src/lib/billing/invoice.ts",
  "src/components/chat/composer.tsx",
  "src/components/chat/message-list.tsx",
  "README.md",
];

export function CommandPaletteMinimal() {
  return (
    <div className="w-72">
      <CommandPalette
        hotkey={null}
        trigger={<CommandPaletteTrigger />}
        items={[
          { id: "new", label: "New chat", icon: <MessageSquarePlus /> },
          { id: "search", label: "Search files", icon: <FileSearch /> },
          { id: "deploy", label: "Deploy preview", icon: <Rocket /> },
        ]}
      />
    </div>
  );
}
```

### Agent actions, recents and nested pages (full)

Controlled open state, ⌘K, recents, a nested “Switch agent…” page and an async “Run workflow…” page.

```tsx
"use client";

import { Bot, Database, FolderGit2, KeyRound, Monitor, Moon, Palette, Play, Square, Sun, Workflow } from "lucide-react";
import * as React from "react";
import { Button } from "@kura-ui/react/button";
import { KbdShortcut } from "@kura-ui/react/kbd-shortcut";
import { CommandPalette, type CommandPaletteItem } from "@kura-ui/react/command-palette";

function buildItems(log: (s: string) => void): CommandPaletteItem[] {
  return [
    {
      id: "run-agent",
      label: "Run agent",
      description: "on the current task",
      icon: <Play />,
      group: "Agent",
      shortcut: ["mod", "enter"],
      onSelect: () => log("Agent started"),
    },
    {
      id: "stop-agent",
      label: "Stop agent",
      icon: <Square />,
      group: "Agent",
      shortcut: ["mod", "."],
      onSelect: () => log("Agent stopped"),
    },
    {
      id: "switch-agent",
      label: "Switch agent…",
      icon: <Bot />,
      group: "Agent",
      placeholder: "Pick an agent…",
      children: [
        {
          id: "agent-research",
          label: "Researcher",
          description: "web + citations",
          onSelect: () => log("Researcher"),
        },
        {
          id: "agent-coder",
          label: "Coder",
          description: "repo + terminal",
          onSelect: () => log("Coder"),
        },
        {
          id: "agent-analyst",
          label: "Analyst",
          description: "SQL + charts",
          onSelect: () => log("Analyst"),
        },
      ],
    },
    {
      id: "workflows",
      label: "Run workflow…",
      icon: <Workflow />,
      group: "Agent",
      loadChildren: async () => {
        await wait(1200);
        return [
          { id: "wf-triage", label: "Triage new issues", onSelect: () => log("Triage running") },
          { id: "wf-digest", label: "Weekly digest", onSelect: () => log("Digest running") },
          { id: "wf-migrate", label: "Migrate schema", disabled: true },
        ];
      },
    },
    {
      id: "context-repo",
      label: "Add repository",
      icon: <FolderGit2 />,
      group: "Context",
      keywords: ["github", "git"],
      onSelect: () => log("Repository added"),
    },
    {
      id: "context-db",
      label: "Connect database",
      icon: <Database />,
      group: "Context",
      keywords: ["postgres", "sql"],
      onSelect: () => log("Database connected"),
    },
    {
      id: "theme",
      label: "Change theme…",
      icon: <Palette />,
      group: "Settings",
      children: [
        { id: "theme-light", label: "Light", icon: <Sun />, onSelect: () => log("Light theme") },
        { id: "theme-dark", label: "Dark", icon: <Moon />, onSelect: () => log("Dark theme") },
        {
          id: "theme-system",
          label: "System",
          icon: <Monitor />,
          onSelect: () => log("System theme"),
        },
      ],
    },
    {
      id: "keys",
      label: "API keys",
      icon: <KeyRound />,
      group: "Settings",
      shortcut: ["mod", ","],
      onSelect: () => log("API keys"),
    },
  ];
}

const wait = (ms: number) => new Promise((r) => setTimeout(r, ms));

export function CommandPaletteFull() {
  const [open, setOpen] = React.useState(false);
  const [last, setLast] = React.useState("Nothing run yet");
  const [recent, setRecent] = React.useState<string[]>(["context-repo", "run-agent"]);
  const items = React.useMemo(() => buildItems(setLast), []);
  return (
    <div className="flex flex-col items-center gap-3">
      <Button variant="secondary" onClick={() => setOpen(true)}>
        Open palette
      </Button>
      <CommandPalette
        items={items}
        open={open}
        onOpenChange={setOpen}
        hotkey={["mod", "k"]}
        recent={recent}
        onRecentChange={setRecent}
        recentLimit={3}
        placeholder="Run an agent, add context, change settings…"
        emptyMessage="No commands match"
        label="Agent commands"
      />
      <KbdShortcut keys={["mod", "k"]} label="or press" />
      <p className="text-kura-fg-subtle text-xs" aria-live="polite">
        {last}
      </p>
    </div>
  );
}
```

### Server-side search (composition)

onQueryChange fetches results into `items` while `loading` shows skeleton rows.

```tsx
"use client";

import { FileSearch } from "lucide-react";
import * as React from "react";
import { CommandPalette, type CommandPaletteItem, CommandPaletteTrigger } from "@kura-ui/react/command-palette";

const files = [
  "src/app/page.tsx",
  "src/app/layout.tsx",
  "src/lib/auth.ts",
  "src/lib/billing/invoice.ts",
  "src/components/chat/composer.tsx",
  "src/components/chat/message-list.tsx",
  "README.md",
];

export function CommandPaletteAsyncSearch() {
  const [results, setResults] = React.useState<CommandPaletteItem[]>([]);
  const [loading, setLoading] = React.useState(false);
  const timer = React.useRef<ReturnType<typeof setTimeout> | null>(null);

  const search = (q: string) => {
    if (timer.current) clearTimeout(timer.current);
    if (!q.trim()) {
      setResults([]);
      setLoading(false);
      return;
    }
    setLoading(true);
    timer.current = setTimeout(() => {
      setResults(
        files
          .filter((f) => f.toLowerCase().includes(q.toLowerCase().split(" ")[0] ?? ""))
          .map((f) => ({
            id: f,
            label: f.split("/").pop() ?? f,
            description: f,
            icon: <FileSearch />,
            group: "Files",
          })),
      );
      setLoading(false);
    }, 500);
  };

  return (
    <div className="w-80">
      <CommandPalette
        hotkey={null}
        trigger={
          <CommandPaletteTrigger placeholder="Search the codebase…" shortcut={["mod", "p"]} />
        }
        items={results}
        loading={loading}
        onQueryChange={search}
        placeholder="Type a file name…"
        emptyMessage="Type to search 7 files"
      />
    </div>
  );
}
```

## Dependencies

- npm: `lucide-react`, `radix-ui`
- Kura registry items: `kura-theme`, `kbd`, `kura-keys`, `use-controllable-state`, `use-hotkey`, `utils`
- Related: `slash-command-menu`, `model-picker`, `kbd-shortcut`, `prompt-suggestions`

---

# Composer

> Prompt input for chat and agents: auto-growing textarea, attachments, toolbar slot, send→stop button, paste/drop files and a length hint.

- **Slug:** `composer` · **Category:** input · **Status:** beta
- **Import:** `import { Composer, ComposerActions, ComposerAttachButton, ComposerAttachments, ComposerHint, ComposerInput, ComposerMessage, ComposerStatus, ComposerSubmit, ComposerToolbar, ComposerTools } from "@kura-ui/react/composer";`
- **Docs:** https://kuro.abstergo.fyi/components/composer
- **Registry item:** https://kuro.abstergo.fyi/r/composer.json
- **Tags:** prompt, chat, input, textarea, composer, send, attachments, streaming

## Install

```bash
# shadcn registry (copies source into your project)
npx shadcn@latest add https://kuro.abstergo.fyi/r/composer.json
# Kura CLI (same, plus dependency resolution and --json output)
npx @kura-ui/cli add composer
# npm package
npm install @kura-ui/react
```

## When to use

- The message box of a chat UI or agent console (“Ask anything…”).
- Any prompt field that should send on Enter, accept pasted or dropped files, and stop a streaming response.
- A prompt input that hosts a model picker, tool toggles, voice input or a slash-command menu in its toolbar.

## When not to use

- A single-line search or filter field — use a plain input or command-palette.
- Showing attachments outside an input (sent messages, file lists) — use attachment.
- Picking a model on its own — use model-picker.
- Voice-only input — use voice-dictation (it can also feed a composer).

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `value` | `string` | — | no | Controlled text. |
| `defaultValue` | `string` | `""` | no | Initial text when uncontrolled. |
| `onValueChange` | `(value: string) => void` | — | no | Called on every text change. |
| `attachments` | `AttachmentItem[]` | — | no | Controlled attachments ({ id, name, size?, type?, url?, status?, progress?, error?, file? }). |
| `defaultAttachments` | `AttachmentItem[]` | — | no | Initial attachments when uncontrolled. |
| `onAttachmentsChange` | `(attachments: AttachmentItem[]) => void` | — | no | Called when files are added or removed. |
| `onFilesAdded` | `(items: AttachmentItem[]) => void` | — | no | Called with newly accepted files (paste, drop or picker) — start uploads here and update `attachments` with status/progress. |
| `onFilesRejected` | `(files: File[]) => void` | — | no | Called with files rejected by accept, maxFileSize or maxFiles. |
| `onSubmit` | `(message: ComposerMessage) => void` | — | no | Send handler: receives { text (trimmed), attachments }. Not called while empty, over maxLength, uploading or busy. |
| `onStop` | `() => void` | — | no | Called by the stop button and by Escape while status is submitted or streaming. |
| `status` | `"idle" \| "submitted" \| "streaming" \| "error"` | `"idle"` | no | Request lifecycle. submitted = waiting for the first token (stop button with a travelling arc), streaming = model writing (stop button). |
| `disabled` | `boolean` | `false` | no | Disable typing, attaching and sending (60% opacity). |
| `maxLength` | `number` | — | no | Character limit. The hint turns amber at 90% and red above; sending is blocked when over. |
| `submitKey` | `"enter" \| "mod+enter"` | `"enter"` | no | enter = Enter sends and Shift+Enter adds a newline; mod+enter = ⌘/Ctrl+Enter sends and Enter adds a newline. |
| `accept` | `string \| false` | `""` | no | Allowed files, like <input accept> ("image/*,.pdf"). "" accepts any file; false disables attachments entirely. |
| `maxFiles` | `number` | — | no | Maximum number of attachments. |
| `maxFileSize` | `number` | — | no | Maximum size of one file in bytes. |
| `clearOnSubmit` | `boolean` | `true` | no | Clear text and attachments after a submit. |
| `placeholder` | `string` | — | no | Placeholder for the default layout (only used when Composer has no children). |

Native attributes of the root element, `className` and `ref` are passed through.

## Anatomy

- **Composer** (`data-slot="composer"`) — Root and drop target. data-status, data-focused, data-dragging, data-disabled; aria-busy while submitted/streaming. With no children it renders the complete default layout.
- **ComposerAttachments** (`data-slot="composer-attachments"`) — The attachment row (renders nothing when empty). Uses attachment's AttachmentList.
  - `max`: `number` — Collapse into a +N stack after this many.
- **ComposerInput** (`data-slot="composer-input"`) — Auto-growing <textarea>. Enter/Shift+Enter, IME-safe, paste files, Escape stops. Accepts all textarea props.
  - `minRows`: `number` = `1` — Rows when empty.
  - `maxRows`: `number` = `8` — Rows before it scrolls instead of growing.
- **ComposerToolbar** (`data-slot="composer-toolbar"`) — Bottom row; holds ComposerTools (left) and ComposerActions (right).
- **ComposerTools** (`data-slot="composer-tools"`) — Left group: attach button, model-picker, tool toggles.
- **ComposerActions** (`data-slot="composer-actions"`) — Right group: hint, voice-dictation, submit.
- **ComposerAttachButton** (`data-slot="composer-attach"`) — Paperclip icon button that opens the file picker.
  - `label`: `string` = `"Attach files"` — Accessible label and tooltip.
  - `icon`: `React.ReactNode` — Replace the paperclip.
- **ComposerHint** (`data-slot="composer-hint"`) — Character count with a mini gauge (with maxLength) or a ~token estimate. data-level = ok | near | over.
  - `mode`: `"characters" | "tokens"` — Default: characters when maxLength is set, tokens otherwise.
  - `showAt`: `number` = `0` — Only show once text reaches this fraction of maxLength (e.g. 0.8).
  - `countTokens`: `(text: string) => number` — Custom tokenizer for mode=tokens (default ≈ chars/4).
- **ComposerSubmit** (`data-slot="composer-submit"`) — Send button (ink when ready, quiet when empty) that becomes a stop button while busy; data-mode = send | stop.
  - `sendLabel`: `string` = `"Send message"` — Accessible label while idle.
  - `stopLabel`: `string` = `"Stop generating"` — Accessible label while busy.
  - `tooltip`: `boolean` = `true` — Tooltip with shortcut.

## Accessibility

- The textarea is labelled “Message” by default (override with aria-label or aria-labelledby) and has enterkeyhint=send.
- Over the character limit the textarea gets aria-invalid and the hint tells screen readers the limit was exceeded (announced once, not per keystroke).
- The submit button swaps its accessible name between “Send message” and “Stop generating”; the root sets aria-busy while a response is pending.
- The focus glow is on the whole composer (focus-within), so the textarea's own outline is replaced, never just removed.
- Attachments are a labelled list with “Remove <file>” buttons; removing returns focus to the textarea.
- Reduced motion: The send/stop icon swap and attachment enter/exit become plain fades (no scale or blur); the pending arc stops travelling and pulses instead.

| Keys | Action |
| --- | --- |
| Enter | Send (submitKey=enter). Ignored while an IME is composing. |
| Shift+Enter | Insert a newline |
| Mod+Enter | Send (both submitKey modes) |
| Escape | Stop the response while submitted/streaming |
| Mod+V | Paste text, or attach pasted files/images |

## Notes for agents

- Drive `status` from your chat hook: set "submitted" when you send, "streaming" on the first token, back to "idle" when done; pass `onStop` to abort.
- With the Vercel AI SDK: status maps 1:1 from useChat's status ('ready' → 'idle').
- Compose parts in this order: ComposerAttachments, ComposerInput, ComposerToolbar > (ComposerTools, ComposerActions > ComposerHint, ComposerSubmit).
- Use `useComposer()` inside custom parts to read value, setValue, attachments, addFiles, submit, status.
- Attachment object URLs are revoked when removed, not when sent — the sent message may still display them.
- To insert text from voice-dictation or prompt-suggestions, control `value` and append to it.

## Examples

### Default layout (minimal)

No children: textarea, attach button, hint and send button.

```tsx
"use client";

import { Composer } from "@kura-ui/react/composer";

export function ComposerMinimal() {
  return (
    <div className="w-full max-w-xl">
      <Composer placeholder="Ask anything…" onSubmit={(m) => console.log(m.text)} />
    </div>
  );
}
```

### Controlled, with model picker and tools (full)

Controlled text, simulated submitted → streaming lifecycle with stop, file limits, a character limit and tool toggles.

```tsx
"use client";

import { Globe, Lightbulb } from "lucide-react";
import * as React from "react";
import { ModelPicker, type ModelPickerModel } from "@kura-ui/react/model-picker";
import {
  Composer,
  ComposerActions,
  ComposerAttachButton,
  ComposerAttachments,
  ComposerHint,
  ComposerInput,
  type ComposerMessage,
  type ComposerStatus,
  ComposerSubmit,
  ComposerToolbar,
  ComposerTools,
} from "@kura-ui/react/composer";

const models: ModelPickerModel[] = [
  {
    id: "opus",
    name: "Claude Opus 5.5",
    provider: "Anthropic",
    description: "Most capable for complex, multi-step work.",
    capabilities: ["vision", "tools", "reasoning"],
    contextWindow: 1_000_000,
    speed: 1,
    cost: 3,
  },
  {
    id: "sonnet",
    name: "Claude Sonnet 5.5",
    provider: "Anthropic",
    description: "Balanced speed and intelligence.",
    capabilities: ["vision", "tools", "reasoning"],
    contextWindow: 1_000_000,
    speed: 2,
    cost: 2,
  },
  {
    id: "haiku",
    name: "Claude Haiku 4.5",
    provider: "Anthropic",
    description: "Fastest, for quick answers.",
    capabilities: ["vision", "tools"],
    contextWindow: 200_000,
    speed: 3,
    cost: 1,
  },
];

function ToolToggle({
  pressed,
  onPressedChange,
  icon,
  children,
}: {
  pressed: boolean;
  onPressedChange: (pressed: boolean) => void;
  icon: React.ReactNode;
  children: React.ReactNode;
}) {
  return (
    <button
      type="button"
      aria-pressed={pressed}
      onClick={() => onPressedChange(!pressed)}
      className="inline-flex h-8 cursor-pointer items-center gap-1.5 rounded-kura-lg px-2.5 font-medium text-[13px] text-kura-fg-muted outline-none transition-[background-color,color,box-shadow] duration-(--kura-duration-fast) ease-kura-out hover:bg-kura-hover hover:text-kura-fg focus-visible:shadow-kura-focus aria-pressed:bg-kura-active aria-pressed:text-kura-fg [&_svg]:size-3.5"
    >
      {icon}
      {children}
    </button>
  );
}

export function ComposerFull() {
  const [value, setValue] = React.useState("");
  const [status, setStatus] = React.useState<ComposerStatus>("idle");
  const [model, setModel] = React.useState("sonnet");
  const [search, setSearch] = React.useState(true);
  const [think, setThink] = React.useState(false);
  const [last, setLast] = React.useState<ComposerMessage | null>(null);
  const timers = React.useRef<ReturnType<typeof setTimeout>[]>([]);

  const clear = React.useCallback(() => {
    for (const t of timers.current) clearTimeout(t);
    timers.current = [];
  }, []);
  React.useEffect(() => clear, [clear]);

  return (
    <div className="flex w-full max-w-xl flex-col gap-3">
      <Composer
        value={value}
        onValueChange={setValue}
        status={status}
        maxLength={2000}
        accept="image/*,.pdf,.csv,.md,.txt,.ts,.tsx"
        maxFiles={6}
        maxFileSize={20 * 1024 * 1024}
        submitKey="enter"
        clearOnSubmit
        onSubmit={(message) => {
          setLast(message);
          setStatus("submitted");
          timers.current.push(setTimeout(() => setStatus("streaming"), 1200));
          timers.current.push(setTimeout(() => setStatus("idle"), 4200));
        }}
        onStop={() => {
          clear();
          setStatus("idle");
        }}
      >
        <ComposerAttachments max={4} />
        <ComposerInput placeholder="Message Kura — paste or drop files" minRows={2} maxRows={10} />
        <ComposerToolbar>
          <ComposerTools>
            <ComposerAttachButton />
            <ModelPicker models={models} value={model} onValueChange={setModel} side="top" />
            <ToolToggle pressed={search} onPressedChange={setSearch} icon={<Globe />}>
              Search
            </ToolToggle>
            <ToolToggle pressed={think} onPressedChange={setThink} icon={<Lightbulb />}>
              Think
            </ToolToggle>
          </ComposerTools>
          <ComposerActions>
            <ComposerHint />
            <ComposerSubmit />
          </ComposerActions>
        </ComposerToolbar>
      </Composer>
      <p className="min-h-4 px-1 text-kura-fg-subtle text-xs" aria-live="polite">
        {status === "submitted"
          ? "Sending…"
          : status === "streaming"
            ? "Responding — press Esc to stop"
            : last
              ? `Sent “${last.text.slice(0, 48)}${last.text.length > 48 ? "…" : ""}”${
                  last.attachments.length ? ` with ${last.attachments.length} file(s)` : ""
                }`
              : "Enter to send · Shift+Enter for a new line"}
      </p>
    </div>
  );
}
```

### Submitted, streaming, over limit and disabled (state)

```tsx
import { Composer, ComposerActions, ComposerAttachButton, ComposerHint, ComposerInput, ComposerSubmit, ComposerToolbar, ComposerTools } from "@kura-ui/react/composer";

export function ComposerStates() {
  return (
    <div className="flex w-full max-w-xl flex-col gap-4">
      <Composer defaultValue="Summarise the attached incident report" status="submitted">
        <ComposerInput />
        <ComposerToolbar>
          <ComposerTools>
            <ComposerAttachButton />
          </ComposerTools>
          <ComposerActions>
            <ComposerSubmit />
          </ComposerActions>
        </ComposerToolbar>
      </Composer>
      <Composer
        defaultValue="Draft release notes for v2.4 — keep it under 200 words and lead with the breaking change to the auth middleware."
        status="streaming"
        maxLength={120}
      >
        <ComposerInput />
        <ComposerToolbar>
          <ComposerTools>
            <ComposerAttachButton />
          </ComposerTools>
          <ComposerActions>
            <ComposerHint />
            <ComposerSubmit />
          </ComposerActions>
        </ComposerToolbar>
      </Composer>
      <Composer disabled placeholder="Upgrade to continue the conversation" />
    </div>
  );
}
```

### New chat home (composition)

An empty-chat start: ModelPicker and VoiceDictation in the toolbar, PromptSuggestions chips that fill and focus the input.

```tsx
"use client";

import { ChartLine, Code, FileText, Mail } from "lucide-react";
import * as React from "react";
import { ModelPicker, type ModelPickerModel } from "@kura-ui/react/model-picker";
import { type PromptSuggestion, PromptSuggestions } from "@kura-ui/react/prompt-suggestions";
import { VoiceDictation } from "@kura-ui/react/voice-dictation";
import { Composer, ComposerActions, ComposerAttachButton, ComposerAttachments, ComposerInput, type ComposerStatus, ComposerSubmit, ComposerToolbar, ComposerTools } from "@kura-ui/react/composer";

const models: ModelPickerModel[] = [
  {
    id: "opus",
    name: "Claude Opus 5.5",
    provider: "Anthropic",
    description: "Most capable for complex, multi-step work.",
    capabilities: ["vision", "tools", "reasoning"],
    contextWindow: 1_000_000,
    speed: 1,
    cost: 3,
  },
  {
    id: "sonnet",
    name: "Claude Sonnet 5.5",
    provider: "Anthropic",
    description: "Balanced speed and intelligence.",
    capabilities: ["vision", "tools", "reasoning"],
    contextWindow: 1_000_000,
    speed: 2,
    cost: 2,
  },
  {
    id: "haiku",
    name: "Claude Haiku 4.5",
    provider: "Anthropic",
    description: "Fastest, for quick answers.",
    capabilities: ["vision", "tools"],
    contextWindow: 200_000,
    speed: 3,
    cost: 1,
  },
];

const starters: PromptSuggestion[] = [
  {
    title: "Analyze a CSV",
    prompt: "Find the three biggest drivers of churn in the attached CSV.",
    icon: <ChartLine />,
  },
  {
    title: "Summarize a doc",
    prompt: "Summarize this doc in five bullets for an exec audience.",
    icon: <FileText />,
  },
  {
    title: "Review a diff",
    prompt: "Review this diff for bugs and missing tests.",
    icon: <Code />,
  },
  {
    title: "Draft a reply",
    prompt: "Draft a friendly reply that moves the meeting to next week.",
    icon: <Mail />,
  },
];

export function ComposerNewChat() {
  const [value, setValue] = React.useState("");
  const [interim, setInterim] = React.useState("");
  const [model, setModel] = React.useState("opus");
  const [status, setStatus] = React.useState<ComposerStatus>("idle");
  const inputRef = React.useRef<HTMLTextAreaElement>(null);
  const timer = React.useRef<ReturnType<typeof setTimeout>>(undefined);
  React.useEffect(() => () => clearTimeout(timer.current), []);

  return (
    <div className="flex w-full max-w-xl flex-col items-center gap-5">
      <div className="flex flex-col items-center gap-1 text-center">
        <h3 className="font-medium text-2xl text-kura-fg tracking-tight">
          What are we working on?
        </h3>
        <p className="text-kura-fg-muted text-sm">
          Start typing, dictate, or pick a starting point.
        </p>
      </div>
      <Composer
        value={value}
        onValueChange={setValue}
        status={status}
        accept="image/*,.pdf,.csv,.md,.txt"
        className="w-full"
        onSubmit={() => {
          setStatus("submitted");
          timer.current = setTimeout(() => setStatus("idle"), 1400);
        }}
        onStop={() => {
          clearTimeout(timer.current);
          setStatus("idle");
        }}
      >
        <ComposerAttachments />
        <ComposerInput ref={inputRef} placeholder={interim || "Message Kura…"} minRows={2} />
        <ComposerToolbar>
          <ComposerTools>
            <ComposerAttachButton />
            <ModelPicker models={models} value={model} onValueChange={setModel} side="top" />
          </ComposerTools>
          <ComposerActions>
            <VoiceDictation
              simulate="Compare our Q3 pricing page with the two closest competitors."
              showTranscript={false}
              hotkey={null}
              onInterim={setInterim}
              onStatusChange={(s) => s === "idle" && setInterim("")}
              onTranscript={(text) => setValue((v) => (v ? `${v.trimEnd()} ${text}` : text))}
            />
            <ComposerSubmit />
          </ComposerActions>
        </ComposerToolbar>
      </Composer>
      <PromptSuggestions
        variant="chips"
        label="Starting points"
        suggestions={starters}
        disabled={status !== "idle"}
        onSelect={(prompt) => {
          setValue(prompt);
          inputRef.current?.focus();
        }}
        className="justify-center"
      />
    </div>
  );
}
```

## Dependencies

- npm: `lucide-react`, `motion`
- Kura registry items: `kura-theme`, `attachment`, `icon-button`, `kura-merge-refs`, `kura-motion`, `tooltip`, `use-controllable-state`, `use-reduced-motion`, `utils`
- Related: `attachment`, `model-picker`, `slash-command-menu`, `voice-dictation`, `prompt-suggestions`

---

# Context Meter

> Token / context-window usage as a compact ring or bar with warning and danger thresholds, rolling numbers and a segmented breakdown card.

- **Slug:** `context-meter` · **Category:** agent · **Status:** beta
- **Import:** `import { ContextMeter, ContextSegment } from "@kura-ui/react/context-meter";`
- **Docs:** https://kuro.abstergo.fyi/components/context-meter
- **Registry item:** https://kuro.abstergo.fyi/r/context-meter.json
- **Tags:** tokens, context-window, usage, meter, budget, progress, llm, limits

## Install

```bash
# shadcn registry (copies source into your project)
npx shadcn@latest add https://kuro.abstergo.fyi/r/context-meter.json
# Kura CLI (same, plus dependency resolution and --json output)
npx @kura-ui/cli add context-meter
# npm package
npm install @kura-ui/react
```

## When to use

- Show how much of a model's context window a conversation uses (e.g. in a composer footer or chat header).
- Break usage down by source — system prompt, tool definitions, attached files, history — in a hover card.
- Warn before the context fills up (auto-compaction, truncation) with warning/danger thresholds.
- Show any other token budget (per-request output limit, monthly quota) as a bar.

## When not to use

- Indeterminate progress or “thinking” — use shimmer-text or reasoning.
- Upload or task progress — use a progress bar (or agent-timeline for multi-step work).
- Billing/cost dashboards with history — use a chart.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `max` | `number` | — | yes | Context window size in tokens, e.g. 200000. |
| `used` | `number` | — | no | Tokens used. Default: the sum of `segments`. |
| `segments` | `readonly ContextSegment[]` | — | no | Breakdown: { id, label, tokens, color? }[], e.g. system / tools / files / history. Enables the hover card and the segmented bar. Colors default to ink tints. |
| `variant` | `"ring" \| "bar"` | `"ring"` | no | ring = 18px donut + value for tight toolbars; bar = horizontal (segmented) bar + value. |
| `warningAt` | `number` | `0.7` | no | Fraction (0–1) from which the meter is amber. |
| `dangerAt` | `number` | `0.9` | no | Fraction (0–1) from which the meter is red. |
| `valueDisplay` | `"percent" \| "tokens" \| "none"` | — | no | Value next to the meter: 42% or 84.2k / 200k. Default percent for ring, tokens for bar. |
| `label` | `string` | `"Context"` | no | Name used in the accessible label and the card title (“Context window”). |
| `footer` | `React.ReactNode` | — | no | Note at the bottom of the card. Defaults to a warning sentence at warning/danger levels. |
| `open` | `boolean` | — | no | Hover card open (controlled). |
| `onOpenChange` | `(open: boolean) => void` | — | no | Called when the hover card opens or closes. |

Native attributes of the root element, `className` and `ref` are passed through.

## Anatomy

- **ContextMeter** (`data-slot="context-meter"`) — Trigger button. `data-variant`, `data-level="ok" | "warning" | "danger"`.
- **Ring** (`data-slot="context-meter-ring"`) — SVG donut (aria-hidden).
- **Bar** (`data-slot="context-meter-bar"`) — Track + fill; segmented by `segments` while level is ok, a single amber/red fill above the thresholds.
- **Value** (`data-slot="context-meter-value"`) — Mono tabular value that rolls to new numbers.
- **Card** (`data-slot="context-meter-card"`) — Hover/click card: totals, segmented bar, legend with tokens and % of the window, free space, footer.
- **Segment** (`data-slot="context-meter-segment"`) — One legend row.

## Accessibility

- The meter is a button whose accessible name carries the full reading: “Context: 84,210 of 200,000 tokens used (42%, filling up)”.
- The breakdown opens on hover (300ms delay) and on click/Enter, without moving focus; Escape closes it.
- Levels are conveyed in text (name + card footer), not only by colour.
- Reduced motion: Numbers, ring and bar jump to the new value instead of rolling/growing; the card only fades.

| Keys | Action |
| --- | --- |
| Enter / Space | Open or close the breakdown card |
| Escape | Close the card |

## Notes for agents

- Pass `segments` whenever you know the breakdown; the meter then sums them and gets a hover card. Without segments it is a plain reading (no card).
- Use the provider's real window size for `max` (e.g. 200000) and recount after every turn — counts roll smoothly between values.
- For a quota rather than a context window, set `label` (e.g. "Output") and use variant="bar".

## Examples

### Ring (minimal)

Used and max; nothing else needed.

```tsx
import { ContextMeter } from "@kura-ui/react/context-meter";

export function ContextMeterMinimal() {
  return <ContextMeter used={84_210} max={200_000} />;
}
```

### Ring and bar with a breakdown (full)

Segments, thresholds, value display and a footer. Add tokens to watch the numbers roll into warning and danger.

```tsx
"use client";

import { Plus } from "lucide-react";
import * as React from "react";
import { Button } from "@kura-ui/react/button";
import { ContextMeter, type ContextSegment } from "@kura-ui/react/context-meter";

const BASE: ContextSegment[] = [
  { id: "system", label: "System prompt", tokens: 3_400 },
  { id: "tools", label: "Tool definitions", tokens: 11_800 },
  { id: "files", label: "Attached files", tokens: 38_600 },
  { id: "history", label: "Conversation", tokens: 30_410 },
];

export function ContextMeterFull() {
  const [history, setHistory] = React.useState(30_410);
  const segments = BASE.map((s) => (s.id === "history" ? { ...s, tokens: history } : s));
  return (
    <div className="flex flex-col items-center gap-6">
      <div className="flex items-center gap-6">
        <ContextMeter
          max={200_000}
          segments={segments}
          variant="ring"
          valueDisplay="percent"
          warningAt={0.7}
          dangerAt={0.9}
          label="Context"
        />
        <ContextMeter
          max={200_000}
          segments={segments}
          variant="bar"
          valueDisplay="tokens"
          footer="Files count once per turn; tool definitions are cached."
        />
      </div>
      <div className="flex gap-2">
        <Button variant="secondary" size="sm" onClick={() => setHistory((h) => h + 24_000)}>
          <Plus /> Add 24k tokens
        </Button>
        <Button variant="ghost" size="sm" onClick={() => setHistory(30_410)}>
          Reset
        </Button>
      </div>
    </div>
  );
}
```

### Thresholds (state)

ok, warning and danger bars.

```tsx
import { ContextMeter } from "@kura-ui/react/context-meter";

export function ContextMeterThresholds() {
  return (
    <div className="flex flex-col items-start gap-3">
      <ContextMeter max={128_000} used={52_000} variant="bar" />
      <ContextMeter max={128_000} used={98_500} variant="bar" />
      <ContextMeter max={128_000} used={121_900} variant="bar" />
    </div>
  );
}
```

### In a composer footer (composition)

Next to an IconButton send action.

```tsx
import { ArrowUp } from "lucide-react";
import { IconButton } from "@kura-ui/react/icon-button";
import { ContextMeter, type ContextSegment } from "@kura-ui/react/context-meter";

const BASE: ContextSegment[] = [
  { id: "system", label: "System prompt", tokens: 3_400 },
  { id: "tools", label: "Tool definitions", tokens: 11_800 },
  { id: "files", label: "Attached files", tokens: 38_600 },
  { id: "history", label: "Conversation", tokens: 30_410 },
];

export function ContextMeterInComposer() {
  return (
    <div className="flex w-full max-w-lg flex-col gap-2 rounded-kura-xl bg-kura-surface p-3 shadow-kura-sm">
      <p className="min-h-12 px-1 text-[15px] text-kura-fg-subtle">Ask a follow-up…</p>
      <div className="flex items-center justify-between">
        <ContextMeter max={200_000} segments={BASE} />
        <IconButton
          label="Send"
          variant="primary"
          size="sm"
          icon={<ArrowUp />}
          className="rounded-full"
        />
      </div>
    </div>
  );
}
```

## Dependencies

- npm: none
- Kura registry items: `kura-theme`, `popover`, `use-controllable-state`, `use-reduced-motion`, `utils`
- Related: `composer`, `model-picker`, `message`, `tool-call`

---

# Decode Text

> Text reveal that scrambles glyphs and resolves them left to right, like an AI decoding — width-stable, with the final text read to screen readers at once.

- **Slug:** `decode-text` · **Category:** effects · **Status:** beta
- **Import:** `import { DecodeText } from "@kura-ui/react/decode-text";`
- **Docs:** https://kuro.abstergo.fyi/components/decode-text
- **Registry item:** https://kuro.abstergo.fyi/r/decode-text.json
- **Tags:** text, reveal, scramble, decode, typewriter, animation, mono, hacker

## Install

```bash
# shadcn registry (copies source into your project)
npx shadcn@latest add https://kuro.abstergo.fyi/r/decode-text.json
# Kura CLI (same, plus dependency resolution and --json output)
npx @kura-ui/cli add decode-text
# npm package
npm install @kura-ui/react
```

## When to use

- Revealing a short status or result the agent just produced: “Plan ready”, “Connected to runner-07”.
- Hero taglines or section headings that should arrive with a technical, machine-like flourish.
- IDs, hashes, timings and other mono data appearing after a computation.

## When not to use

- Streaming a model's answer token by token — use streaming-text.
- An in-progress label — use shimmer-text or thinking-indicator.
- Paragraphs or anything longer than a line or two: the effect becomes noise and per-glyph DOM gets heavy.
- Text that changes many times a second (live counters) — render it plainly.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `children` | `string` | — | yes | The final text (a plain string). Changing it replays the reveal. |
| `startOn` | `"mount" \| "view"` | `"mount"` | no | When the first reveal runs: immediately, or the first time ≥ 40% of it scrolls into view (a dim, still scramble shows until then). |
| `trigger` | `string \| number \| boolean` | — | no | Replay whenever this value changes — a counter, an id or a boolean. |
| `duration` | `number` | `1000` | no | Milliseconds for the reveal to sweep the whole text (ease-out). |
| `spread` | `number` | `6` | no | How many characters ahead of the resolved edge scramble actively, in the accent colour. |
| `glyphs` | `string` | — | no | Characters used for scrambling. Default "A–Z 0–9 #%&*+=/<>". Try "01" for binary or a single "·" for a quiet reveal. |
| `as` | `"span" \| "p" \| "div" \| "h1" \| "h2" \| "h3" \| "code"` | `"span"` | no | Element to render. |
| `onComplete` | `() => void` | — | no | Called when a reveal finishes (not called under reduced motion). |

Native attributes of the root element, `className` and `ref` are passed through.

## Anatomy

- **DecodeText** (`data-slot="decode-text"`) — Root element. `data-state` = pending | running | done.
- **Glyphs** (`data-slot="decode-text-glyphs"`) — The visual (aria-hidden) text; plain text once done.
- **Char** (`data-slot="decode-text-char"`) — One glyph slot while decoding. `data-state` = pending | active | done; `data-char` holds the final character.

## Accessibility

- The final text is always present in a visually hidden span, so screen readers read it immediately and once; the scrambling glyphs are aria-hidden.
- Not a live region. Wrap it in role=status if a replay (new text) should be announced.
- Each glyph reserves the width of its final character, so the line never reflows while decoding.
- Reduced motion: No scramble: the final text renders immediately.

## Notes for agents

- Pass a plain string child. For mixed formatting, wrap several DecodeTexts.
- Monospace (`font-kura-mono`) gives the cleanest look; proportional fonts work because each glyph keeps its final width.
- Use `trigger` to replay without changing the text (e.g. when a card re-opens); change `children` to decode new text.
- Keep it to one or two lines and ≤ 1.5s — it should feel like arrival, not waiting.

## Examples

### Decode on mount (minimal)

```tsx
import { DecodeText } from "@kura-ui/react/decode-text";

export function DecodeTextMinimal() {
  return <DecodeText className="font-kura-mono text-kura-fg text-sm">Agent online</DecodeText>;
}
```

### Triggers, glyph sets and fonts (full)

Replay via `trigger`, text changes, `startOn="view"`, a binary glyph set and a proportional font.

```tsx
"use client";

import { RotateCcw } from "lucide-react";
import * as React from "react";
import { Button } from "@kura-ui/react/button";
import { DecodeText } from "@kura-ui/react/decode-text";

const lines = [
  "Plan ready: 3 steps, 2 files",
  "Migration applied to staging",
  "All 214 tests passing",
];

export function DecodeTextFull() {
  const [i, setI] = React.useState(0);
  const [runs, setRuns] = React.useState(0);
  return (
    <div className="flex w-full max-w-md flex-col items-start gap-5">
      <DecodeText
        as="h3"
        trigger={runs}
        duration={1400}
        spread={8}
        className="font-kura-mono font-medium text-kura-fg text-xl tracking-tight"
      >
        {lines[i % lines.length]!}
      </DecodeText>
      <DecodeText
        as="p"
        startOn="view"
        duration={900}
        glyphs="01"
        className="font-kura-mono text-kura-fg-muted text-xs"
      >
        sha 9f3c2e1 · 412 ms · 1,284 tokens
      </DecodeText>
      <DecodeText as="p" duration={1200} className="text-kura-fg-muted text-sm">
        Proportional fonts keep their width while decoding.
      </DecodeText>
      <div className="flex gap-1.5">
        <Button size="sm" variant="secondary" onClick={() => setI((v) => v + 1)}>
          Next message
        </Button>
        <Button size="sm" variant="ghost" onClick={() => setRuns((r) => r + 1)}>
          <RotateCcw /> Replay
        </Button>
      </div>
    </div>
  );
}
```

### Agent connection status (composition)

A status card that decodes its new state inside a polite live region.

```tsx
"use client";

import * as React from "react";
import { Button } from "@kura-ui/react/button";
import { DecodeText } from "@kura-ui/react/decode-text";

export function DecodeTextAgentHandshake() {
  const [connected, setConnected] = React.useState(false);
  return (
    <div className="flex w-full max-w-sm flex-col gap-3 rounded-kura-xl bg-kura-surface p-4 shadow-kura-sm">
      <div className="flex items-center justify-between">
        <span className="text-kura-fg-subtle text-xs uppercase tracking-wide">Remote agent</span>
        <span
          className="size-2 rounded-full bg-kura-accent data-[on=false]:bg-kura-gray-8"
          data-on={connected}
          aria-hidden
        />
      </div>
      <div role="status" aria-live="polite" className="font-kura-mono text-kura-fg text-sm">
        <DecodeText trigger={connected} duration={1100}>
          {connected ? "Connected to build-runner-07" : "Not connected"}
        </DecodeText>
      </div>
      <Button
        size="sm"
        variant={connected ? "secondary" : "primary"}
        onClick={() => setConnected((c) => !c)}
      >
        {connected ? "Disconnect" : "Connect"}
      </Button>
    </div>
  );
}
```

## Dependencies

- npm: none
- Kura registry items: `kura-theme`, `kura-merge-refs`, `use-reduced-motion`, `utils`
- Related: `streaming-text`, `shimmer-text`, `thinking-indicator`

---

# Grain

> Film-grain overlay from a cached SVG-noise tile, with blend modes and an optional compositor-only flicker — texture for gradients and heroes.

- **Slug:** `grain` · **Category:** effects · **Status:** beta
- **Import:** `import { Grain } from "@kura-ui/react/grain";`
- **Docs:** https://kuro.abstergo.fyi/components/grain
- **Registry item:** https://kuro.abstergo.fyi/r/grain.json
- **Tags:** grain, noise, texture, film, overlay, svg, background, effect

## Install

```bash
# shadcn registry (copies source into your project)
npx shadcn@latest add https://kuro.abstergo.fyi/r/grain.json
# Kura CLI (same, plus dependency resolution and --json output)
npx @kura-ui/cli add grain
# npm package
npm install @kura-ui/react
```

## When to use

- Adding a print-like finish on top of a mesh-gradient, aurora or photo.
- Hiding colour banding on large, low-contrast gradients.
- Giving a flat hero or empty-state panel a subtle tactile texture.

## When not to use

- As the background itself — combine it with mesh-gradient or aurora.
- Over body text or dense UI: noise reduces legibility.
- Signalling activity — grain is texture; use border-beam or thinking-indicator.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `opacity` | `number` | `0.12` | no | Strength of the grain, 0–1. 0.08–0.2 is subtle; 0.3+ is stylised. |
| `blend` | `"overlay" \| "soft-light" \| "multiply" \| "screen" \| "normal"` | `"overlay"` | no | mix-blend-mode. overlay works on mid and dark tones; multiply suits light surfaces; screen suits very dark ones. |
| `scale` | `number` | `1` | no | Grain size multiplier: 1 is fine film grain, 2–3 is coarse. |
| `animated` | `boolean` | `false` | no | Flicker the grain like projected film (a stepped transform, compositor-only). Off by default. |
| `fps` | `number` | `12` | no | Flicker rate when animated. 8–15 reads as film; higher looks like TV static. |

Native attributes of the root element, `className` and `ref` are passed through.

## Anatomy

- **Grain** (`data-slot="grain"`) — Absolutely positioned overlay (`inset-0`, pointer-events none, overflow hidden) carrying opacity and blend mode. `data-animated` mirrors `animated`.
- **Layer** (`data-slot="grain-layer"`) — Oversized noise layer (200%) that the flicker translates.

## Accessibility

- Decorative and aria-hidden; it never receives pointer events.
- Keep opacity low over text; grain can lower perceived contrast.
- Reduced motion: The flicker stops; the grain stays as a static texture.

## Notes for agents

- The parent must be positioned (`relative`) — Grain is `absolute inset-0`. Render it last so it sits on top, and lift text above it with `relative z-10` if needed.
- Server-safe: no hooks, no 'use client'.
- On near-white surfaces `overlay` is almost invisible by design; use `blend="multiply"` with opacity ~0.06 there.
- One Grain per surface; it tiles a 180px image, so cost does not grow with size.

## Examples

### Grain over a gradient (minimal)

Place it inside any positioned element.

```tsx
import { Grain } from "@kura-ui/react/grain";

export function GrainMinimal() {
  return (
    <div className="relative h-48 w-full max-w-md overflow-hidden rounded-kura-xl bg-[radial-gradient(120%_90%_at_20%_10%,var(--kura-accent-subtle),var(--kura-gray-3))] shadow-kura-sm">
      <Grain />
    </div>
  );
}
```

### Blend modes, opacity, scale, flicker (full)

Compare every blend mode on a light and a dark surface.

```tsx
"use client";

import * as React from "react";
import { Button } from "@kura-ui/react/button";
import { Grain, type GrainBlend } from "@kura-ui/react/grain";

const blends: GrainBlend[] = ["overlay", "soft-light", "multiply", "screen", "normal"];

export function GrainFull() {
  const [blend, setBlend] = React.useState<GrainBlend>("overlay");
  const [opacity, setOpacity] = React.useState(0.35);
  const [scale, setScale] = React.useState(1);
  const [animated, setAnimated] = React.useState(true);
  return (
    <div className="flex w-full max-w-xl flex-col gap-4">
      <div className="grid h-56 grid-cols-2 overflow-hidden rounded-kura-xl shadow-kura-sm">
        {["bg-kura-accent", "bg-kura-gray-12"].map((bg) => (
          <div key={bg} className={`relative ${bg}`}>
            <Grain opacity={opacity} blend={blend} scale={scale} animated={animated} fps={12} />
          </div>
        ))}
      </div>
      <div className="flex flex-wrap items-center gap-1.5">
        {blends.map((b) => (
          <Button
            key={b}
            size="xs"
            variant={b === blend ? "secondary" : "ghost"}
            aria-pressed={b === blend}
            onClick={() => setBlend(b)}
          >
            {b}
          </Button>
        ))}
        <Button
          size="xs"
          variant="ghost"
          className="ml-auto"
          aria-pressed={animated}
          onClick={() => setAnimated((a) => !a)}
        >
          Flicker {animated ? "on" : "off"}
        </Button>
      </div>
      <div className="grid grid-cols-2 gap-6 text-kura-fg-muted text-xs">
        <label className="flex flex-col gap-1.5">
          Opacity {opacity.toFixed(2)}
          <input
            type="range"
            min={0}
            max={0.6}
            step={0.01}
            value={opacity}
            onChange={(e) => setOpacity(Number(e.target.value))}
            className="accent-kura-accent"
          />
        </label>
        <label className="flex flex-col gap-1.5">
          Scale {scale.toFixed(1)}
          <input
            type="range"
            min={0.5}
            max={3}
            step={0.1}
            value={scale}
            onChange={(e) => setScale(Number(e.target.value))}
            className="accent-kura-accent"
          />
        </label>
      </div>
    </div>
  );
}
```

### On a mesh gradient (composition)

The classic pairing: MeshGradient with Grain as its last child.

```tsx
import { MeshGradient } from "@kura-ui/react/mesh-gradient";
import { Grain } from "@kura-ui/react/grain";

export function GrainOnGradient() {
  return (
    <MeshGradient
      colors="signal"
      className="flex h-64 w-full items-end rounded-kura-2xl p-6 shadow-kura-md"
    >
      <p className="relative z-10 max-w-xs font-medium text-kura-fg text-lg tracking-tight">
        A little grain turns a gradient into a print.
      </p>
      <Grain opacity={0.3} blend="overlay" />
    </MeshGradient>
  );
}
```

## Dependencies

- npm: none
- Kura registry items: `kura-theme`, `utils`
- Related: `mesh-gradient`, `aurora`, `shader-canvas`, `particle-field`

---

# Icon Button

> Square icon-only button with a mandatory accessible label and an automatic tooltip (with optional shortcut).

- **Slug:** `icon-button` · **Category:** primitives · **Status:** stable
- **Import:** `import { IconButton } from "@kura-ui/react/icon-button";`
- **Docs:** https://kuro.abstergo.fyi/components/icon-button
- **Registry item:** https://kuro.abstergo.fyi/r/icon-button.json
- **Tags:** button, icon, toolbar, action, tooltip

## Install

```bash
# shadcn registry (copies source into your project)
npx shadcn@latest add https://kuro.abstergo.fyi/r/icon-button.json
# Kura CLI (same, plus dependency resolution and --json output)
npx @kura-ui/cli add icon-button
# npm package
npm install @kura-ui/react
```

## When to use

- Toolbar and composer actions: attach, mic, send, stop, copy, retry.
- Any action represented only by an icon.

## When not to use

- Actions that need a visible text label — use button.
- Toggles with on/off state in a group — compose button with aria-pressed.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `label` | `string` | — | yes | Accessible name and tooltip text. |
| `icon` | `React.ReactNode` | — | yes | The icon element, e.g. <ArrowUp /> from lucide-react. |
| `tooltip` | `boolean` | `true` | no | Show label (and shortcut) in a tooltip. |
| `shortcut` | `readonly KeyName[]` | — | no | Shortcut shown in the tooltip (display only). |
| `tooltipSide` | `"top" \| "right" \| "bottom" \| "left"` | `"top"` | no | Tooltip side. |
| `variant` | `"primary" \| "secondary" \| "ghost" \| "outline" \| "accent" \| "danger"` | `"ghost"` | no | Same variants as button; defaults to ghost. |
| `size` | `"xs" \| "sm" \| "md" \| "lg"` | `"md"` | no | 24 / 28 / 32 / 40px square. |

Native attributes of the root element, `className` and `ref` are passed through.

## Accessibility

- `label` becomes aria-label, so the control always has an accessible name.
- The tooltip opens on focus, so keyboard users see the label and shortcut too.
- Reduced motion: Inherits button: no press scale; tooltip fades without travel.

| Keys | Action |
| --- | --- |
| Enter / Space | Activate |

## Notes for agents

- Never pass aria-label; use `label`. The shortcut is display-only — bind it with useHotkey or kbd-shortcut.

## Examples

### Basic (minimal)

```tsx
import { Copy } from "lucide-react";
import { IconButton } from "@kura-ui/react/icon-button";

export function IconButtonMinimal() {
  return <IconButton label="Copy" icon={<Copy />} />;
}
```

### Composer toolbar (full)

```tsx
import { ArrowUp, Mic, Paperclip, RotateCcw } from "lucide-react";
import { IconButton } from "@kura-ui/react/icon-button";

export function IconButtonFull() {
  return (
    <div className="flex items-center gap-1 rounded-kura-xl bg-kura-surface p-1.5 shadow-kura-sm">
      <IconButton label="Attach file" icon={<Paperclip />} size="sm" />
      <IconButton label="Dictate" icon={<Mic />} size="sm" shortcut={["mod", "d"]} />
      <IconButton label="Retry" icon={<RotateCcw />} size="sm" tooltipSide="bottom" />
      <span className="mx-1 h-4 w-px bg-kura-border" />
      <IconButton
        label="Send"
        icon={<ArrowUp />}
        size="sm"
        variant="primary"
        shortcut={["mod", "enter"]}
        className="rounded-full"
      />
      <IconButton
        label="Sending disabled"
        icon={<ArrowUp />}
        size="sm"
        variant="secondary"
        disabled
        tooltip={false}
      />
    </div>
  );
}
```

### Message action bar (composition)

Copy with a confirm swap, pressed feedback toggles, a loading regenerate and shortcut tooltips under an assistant reply.

```tsx
"use client";

import { Check, Copy, RotateCcw, Share, ThumbsDown, ThumbsUp, Volume2 } from "lucide-react";
import * as React from "react";
import { IconButton } from "@kura-ui/react/icon-button";

export function IconButtonMessageActions() {
  const [copied, setCopied] = React.useState(false);
  const [rating, setRating] = React.useState<"up" | "down" | null>(null);
  const [regenerating, setRegenerating] = React.useState(false);
  const timers = React.useRef<ReturnType<typeof setTimeout>[]>([]);
  React.useEffect(() => () => timers.current.forEach(clearTimeout), []);

  const copy = () => {
    setCopied(true);
    timers.current.push(setTimeout(() => setCopied(false), 1600));
  };
  const regenerate = () => {
    setRegenerating(true);
    timers.current.push(setTimeout(() => setRegenerating(false), 1400));
  };

  return (
    <article
      aria-label="Assistant reply"
      className="flex w-full max-w-lg flex-col gap-3 rounded-kura-xl bg-kura-surface p-4 shadow-kura-sm"
    >
      <p className="text-[15px] text-kura-fg leading-relaxed">
        The dip lines up with the 2.4 release: onboarding completion fell from 71% to 58% the day
        the new permissions step shipped. Moving that step after the first project is created should
        recover most of it.
      </p>
      <div className="flex items-center justify-between gap-3">
        <div
          role="toolbar"
          aria-label="Message actions"
          className="-ml-1.5 flex items-center gap-0.5"
        >
          <IconButton
            label={copied ? "Copied" : "Copy"}
            icon={copied ? <Check className="text-kura-success-text" /> : <Copy />}
            size="sm"
            shortcut={["mod", "shift", "c"]}
            onClick={copy}
          />
          <IconButton
            label="Good response"
            icon={<ThumbsUp />}
            size="sm"
            aria-pressed={rating === "up"}
            className="aria-pressed:bg-kura-active aria-pressed:text-kura-fg"
            onClick={() => setRating((r) => (r === "up" ? null : "up"))}
          />
          <IconButton
            label="Bad response"
            icon={<ThumbsDown />}
            size="sm"
            aria-pressed={rating === "down"}
            className="aria-pressed:bg-kura-active aria-pressed:text-kura-fg"
            onClick={() => setRating((r) => (r === "down" ? null : "down"))}
          />
          <IconButton label="Read aloud" icon={<Volume2 />} size="sm" />
          <span aria-hidden className="mx-1 h-4 w-px bg-kura-border" />
          <IconButton
            label="Regenerate"
            icon={<RotateCcw />}
            size="sm"
            shortcut={["mod", "r"]}
            loading={regenerating}
            onClick={regenerate}
          />
          <IconButton label="Share" icon={<Share />} size="sm" />
        </div>
        <p className="shrink-0 font-kura-mono text-kura-fg-subtle text-xs tabular-nums">
          Sonnet 5.5 · 2.1s
        </p>
      </div>
    </article>
  );
}
```

## Dependencies

- npm: none
- Kura registry items: `kura-theme`, `button`, `kura-keys`, `tooltip`, `utils`
- Related: `button`, `tooltip`, `kbd-shortcut`

---

# Kbd

> Keyboard key or key combo, platform-aware (⌘ on Apple, Ctrl elsewhere) and hydration-safe.

- **Slug:** `kbd` · **Category:** primitives · **Status:** stable
- **Import:** `import { Kbd } from "@kura-ui/react/kbd";`
- **Docs:** https://kuro.abstergo.fyi/components/kbd
- **Registry item:** https://kuro.abstergo.fyi/r/kbd.json
- **Tags:** keyboard, key, shortcut, kbd, hotkey

## Install

```bash
# shadcn registry (copies source into your project)
npx shadcn@latest add https://kuro.abstergo.fyi/r/kbd.json
# Kura CLI (same, plus dependency resolution and --json output)
npx @kura-ui/cli add kbd
# npm package
npm install @kura-ui/react
```

## When to use

- Show a key or combo inline in text, menus, tooltips or docs.
- Building blocks for shortcut hints inside other components.

## When not to use

- A labelled hint that should also bind the shortcut — use kbd-shortcut.
- A shortcut inside a tooltip — pass `shortcut` to tooltip.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `keys` | `readonly KeyName[]` | — | no | Combo to render, e.g. ["mod", "k"]. When omitted, children render as one key. |
| `variant` | `"raised" \| "ghost"` | `"raised"` | no | raised = standalone keycap; ghost = inline inside buttons, tooltips and menus. |
| `size` | `"sm" \| "md"` | `"md"` | no | 18px or 22px tall. |
| `pressed` | `boolean` | `false` | no | Render the pressed state. |

Native attributes of the root element, `className` and `ref` are passed through.

## Anatomy

- **Kbd** (`data-slot="kbd"`) — Outer <kbd>. For combos it contains sr-only label text.
- **Key** (`data-slot="kbd-key"`) — One nested <kbd> per key in a combo (aria-hidden).

## Accessibility

- Combos include visually hidden text with one spoken label (“Command K”); the glyph keys are aria-hidden.
- Platform detection runs after hydration, so server HTML shows Ctrl and updates to ⌘ on Apple devices.
- Reduced motion: Pressed state does not translate.

## Notes for agents

- Use `mod` for the primary modifier; never hard-code ⌘ or Ctrl glyphs.

## Examples

### Single key (minimal)

```tsx
import { Kbd } from "@kura-ui/react/kbd";

export function KbdMinimal() {
  return <Kbd>Esc</Kbd>;
}
```

### Combos, variants, sizes (full)

```tsx
import { Kbd } from "@kura-ui/react/kbd";

export function KbdFull() {
  return (
    <div className="flex flex-col items-center gap-4 text-kura-fg-muted text-sm">
      <p className="flex items-center gap-2">
        Search with <Kbd keys={["mod", "k"]} /> or <Kbd>/</Kbd>
      </p>
      <div className="flex items-center gap-3">
        <Kbd keys={["mod", "shift", "p"]} size="sm" />
        <Kbd keys={["alt", "enter"]} variant="ghost" />
        <Kbd keys={["up"]} pressed />
      </div>
    </div>
  );
}
```

### Keyboard shortcut sheet (composition)

A grouped help sheet of combos and alternatives with an IconButton close bound to Esc.

```tsx
import { X } from "lucide-react";
import { IconButton } from "@kura-ui/react/icon-button";
import { Kbd } from "@kura-ui/react/kbd";

const shortcutGroups: Array<{
  title: string;
  items: Array<{ label: string; keys: string[]; alt?: string[] }>;
}> = [
  {
    title: "General",
    items: [
      { label: "Command palette", keys: ["mod", "k"] },
      { label: "New chat", keys: ["mod", "shift", "o"] },
      { label: "Toggle sidebar", keys: ["mod", "b"] },
      { label: "Search chats", keys: ["/"] },
    ],
  },
  {
    title: "Composer",
    items: [
      { label: "Send message", keys: ["enter"] },
      { label: "New line", keys: ["shift", "enter"] },
      { label: "Stop generating", keys: ["esc"] },
      { label: "Edit last message", keys: ["up"] },
    ],
  },
  {
    title: "Conversation",
    items: [
      { label: "Copy last reply", keys: ["mod", "shift", "c"] },
      { label: "Regenerate", keys: ["mod", "r"] },
      { label: "Previous / next reply", keys: ["alt", "up"], alt: ["alt", "down"] },
      { label: "Jump to latest", keys: ["mod", "down"] },
    ],
  },
  {
    title: "Voice & files",
    items: [
      { label: "Dictate", keys: ["mod", "shift", "d"] },
      { label: "Push to talk", keys: ["alt", "space"] },
      { label: "Attach a file", keys: ["mod", "u"] },
      { label: "Switch model", keys: ["mod", "shift", "m"] },
    ],
  },
];

export function KbdShortcutSheet() {
  return (
    <section
      aria-labelledby="shortcut-sheet-title"
      className="w-full max-w-2xl rounded-kura-xl bg-kura-surface shadow-kura-md"
    >
      <header className="flex items-center justify-between gap-4 border-kura-border-subtle border-b px-5 py-4">
        <div className="flex flex-col gap-0.5">
          <h3 id="shortcut-sheet-title" className="font-medium text-[15px] text-kura-fg">
            Keyboard shortcuts
          </h3>
          <p className="text-kura-fg-muted text-[13px]">
            Press <Kbd keys={["mod", "/"]} size="sm" /> any time to open this sheet.
          </p>
        </div>
        <IconButton label="Close" icon={<X />} size="sm" shortcut={["esc"]} tooltipSide="left" />
      </header>
      <div className="grid gap-x-8 gap-y-5 px-5 py-4 sm:grid-cols-2">
        {shortcutGroups.map((group) => (
          <div key={group.title} className="flex flex-col gap-1">
            <h4 className="pb-1 font-medium text-kura-fg-subtle text-xs">{group.title}</h4>
            <dl className="flex flex-col">
              {group.items.map((item) => (
                <div
                  key={item.label}
                  className="flex h-8 items-center justify-between gap-4 text-[13px]"
                >
                  <dt className="truncate text-kura-fg-muted">{item.label}</dt>
                  <dd className="flex shrink-0 items-center gap-1.5">
                    <Kbd keys={item.keys} size="sm" />
                    {item.alt && (
                      <>
                        <span className="text-kura-fg-subtle text-xs">/</span>
                        <Kbd keys={item.alt} size="sm" />
                      </>
                    )}
                  </dd>
                </div>
              ))}
            </dl>
          </div>
        ))}
      </div>
    </section>
  );
}
```

## Dependencies

- npm: none
- Kura registry items: `kura-theme`, `kura-keys`, `use-platform`, `utils`
- Related: `kbd-shortcut`, `tooltip`, `command-palette`

---

# Kbd Shortcut

> Labelled keyboard-shortcut hint (“Send ⌘↵”) that can also bind the shortcut and light its keys while pressed.

- **Slug:** `kbd-shortcut` · **Category:** input · **Status:** beta
- **Import:** `import { KbdShortcut } from "@kura-ui/react/kbd-shortcut";`
- **Docs:** https://kuro.abstergo.fyi/components/kbd-shortcut
- **Registry item:** https://kuro.abstergo.fyi/r/kbd-shortcut.json
- **Tags:** keyboard, shortcut, hotkey, hint, kbd, composer, accelerator

## Install

```bash
# shadcn registry (copies source into your project)
npx shadcn@latest add https://kuro.abstergo.fyi/r/kbd-shortcut.json
# Kura CLI (same, plus dependency resolution and --json output)
npx @kura-ui/cli add kbd-shortcut
# npm package
npm install @kura-ui/react
```

## When to use

- Hints under or inside a prompt composer: “⌘↵ to send”, “Esc to stop”.
- Advertise and bind a global shortcut in one element (e.g. ⌘K for search, ⌘J to toggle a panel).
- Empty states and onboarding that teach shortcuts.

## When not to use

- Showing a single key or combo without a label or binding — use kbd.
- A shortcut inside a tooltip — pass `shortcut` to tooltip or icon-button instead.
- Binding a shortcut with no visible hint — call the useHotkey hook directly.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `keys` | `readonly KeyName[]` | — | yes | The combo, e.g. ["mod", "enter"]. `mod` renders ⌘ on Apple platforms and Ctrl elsewhere. |
| `label` | `React.ReactNode` | — | no | Short action label shown before the keys, e.g. "Send". |
| `onTrigger` | `(event: KeyboardEvent) => void` | — | no | Bind the combo on `document` and call this when pressed. Omit for a display-only hint. |
| `enabled` | `boolean` | `true` | no | Enable/disable the binding without hiding the hint (renders dimmed when false). |
| `allowInInputs` | `boolean` | — | no | Fire while typing in inputs. Defaults to true only when the combo contains a modifier. |
| `variant` | `"raised" \| "ghost"` | `"raised"` | no | Keycap style. Use ghost inside buttons and dense toolbars. |
| `size` | `"sm" \| "md"` | `"sm"` | no | Keycap size. |

Native attributes of the root element, `className` and `ref` are passed through.

## Anatomy

- **KbdShortcut** (`data-slot="kbd-shortcut"`) — Wrapper; exposes `data-pressed` and `data-bound`.
- **Label** (`data-slot="kbd-shortcut-label"`) — Optional action label.
- **Kbd** (`data-slot="kbd"`) — The combo, rendered with the kbd primitive.

## Accessibility

- Renders a semantic <kbd> combo with visually hidden spoken text (e.g. “Command Enter”); individual glyphs are aria-hidden.
- The binding is global (document keydown); without a modifier it is ignored while the user types in inputs.
- It is a hint, not a control: the action must also be reachable by a focusable button.
- Reduced motion: The 1px key press travel is removed; colour change remains.

| Keys | Action |
| --- | --- |
| The configured combo | Calls onTrigger and shows the keys pressed |

## Notes for agents

- Use `mod` (not `meta`/`ctrl`) for the primary modifier so it is correct on every platform.
- Only one mounted KbdShortcut should bind a given combo; render the others display-only (no onTrigger).
- Key names follow KeyboardEvent.key plus aliases: mod, cmd, ctrl, alt/option, shift, enter, esc, up/down/left/right, space.

## Examples

### Display-only hint (minimal)

```tsx
import { KbdShortcut } from "@kura-ui/react/kbd-shortcut";

export function KbdShortcutMinimal() {
  return <KbdShortcut keys={["mod", "enter"]} label="Send" />;
}
```

### Bound shortcut (full)

Press the combo: the keys light up and a counter increments.

```tsx
"use client";

import * as React from "react";
import { KbdShortcut } from "@kura-ui/react/kbd-shortcut";

export function KbdShortcutFull() {
  const [count, setCount] = React.useState(0);
  return (
    <div className="flex flex-col items-center gap-3">
      <KbdShortcut
        keys={["mod", "j"]}
        label="Toggle panel"
        size="md"
        variant="raised"
        allowInInputs
        enabled
        onTrigger={() => setCount((c) => c + 1)}
      />
      <p className="text-kura-fg-muted text-xs tabular-nums" aria-live="polite">
        Triggered {count} {count === 1 ? "time" : "times"}
      </p>
    </div>
  );
}
```

### Composer footer hints (composition)

A row of hints as used under a prompt composer.

```tsx
import { KbdShortcut } from "@kura-ui/react/kbd-shortcut";

export function KbdShortcutComposerHints() {
  return (
    <div className="flex w-full max-w-md items-center justify-between rounded-kura-lg bg-kura-surface px-3 py-2 shadow-kura-sm">
      <div className="flex items-center gap-3">
        <KbdShortcut keys={["/"]} label="Commands" variant="ghost" />
        <KbdShortcut keys={["@"]} label="Context" variant="ghost" />
      </div>
      <KbdShortcut keys={["mod", "enter"]} label="Send" />
    </div>
  );
}
```

## Dependencies

- npm: none
- Kura registry items: `kura-theme`, `kbd`, `kura-keys`, `use-hotkey`, `utils`
- Related: `kbd`, `tooltip`, `icon-button`, `composer`, `command-palette`

---

# Mesh Gradient

> Animated WebGL mesh gradient that blends up to six colours in OKLab, with distortion, swirl, grain and a pointer lens — for heroes and empty states.

- **Slug:** `mesh-gradient` · **Category:** effects · **Status:** beta
- **Import:** `import { MeshGradient } from "@kura-ui/react/mesh-gradient";`
- **Docs:** https://kuro.abstergo.fyi/components/mesh-gradient
- **Registry item:** https://kuro.abstergo.fyi/r/mesh-gradient.json
- **Tags:** gradient, mesh, webgl, shader, background, hero, oklab, ambient

## Install

```bash
# shadcn registry (copies source into your project)
npx shadcn@latest add https://kuro.abstergo.fyi/r/mesh-gradient.json
# Kura CLI (same, plus dependency resolution and --json output)
npx @kura-ui/cli add mesh-gradient
# npm package
npm install @kura-ui/react
```

## When to use

- A hero, landing or onboarding section that needs a calm, living background behind a headline.
- An empty state or a 'start a conversation' panel that should feel warm instead of blank.
- A card or banner announcing an AI feature, using the theme-aware `signal` preset.
- Any container where content should sit on a soft, slowly moving colour field (pass children).

## When not to use

- Northern-lights curtains or a night-sky feel — use aurora.
- Showing that an agent is listening or speaking — use agent-orb.
- Signalling that a container is busy — use border-beam (it outlines instead of filling).
- Small inline indicators — use thinking-indicator or shimmer-text.
- Just adding texture to an existing background — use grain.
- A fully custom GLSL effect — build it on shader-canvas.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `colors` | `"signal" \| "paper" \| "jade" \| "dusk" \| "ember" \| "glacier" \| readonly string[]` | `"signal"` | no | A preset, or 2–6 CSS colours (OKLCH, hex, rgb, `var(--kura-*)`). `signal` and `paper` are built from tokens and follow light/dark; the others are fixed palettes. |
| `distortion` | `number` | `0.5` | no | Organic noise warping of the colour field, 0–1. |
| `swirl` | `number` | `0.25` | no | Twist around the centre, 0–1. Keep ≤ 0.5 behind text. |
| `speed` | `number` | `1` | no | Animation speed multiplier. 0 renders a still frame. |
| `grain` | `number` | `0.12` | no | Film-grain amount, 0–1. A little grain hides banding on large surfaces. |
| `interactive` | `boolean` | `true` | no | Gently lens the colour field toward the pointer while it is over the element. |
| `paused` | `boolean` | `false` | no | Freeze the animation on the current frame. |
| `seed` | `number` | `0` | no | Changes where the colour wells start, so two gradients on a page differ. |
| `maxDpr` | `number` | `1.5` | no | Device-pixel-ratio cap. The field is soft, so 1–1.5 keeps it cheap. |
| `children` | `React.ReactNode` | — | no | Content rendered on top of the gradient (it sits in normal flow). |

Native attributes of the root element, `className` and `ref` are passed through.

## Anatomy

- **MeshGradient** (`data-slot="mesh-gradient"`) — Root container (`relative isolate overflow-hidden`). Size it with classes. `data-state` = animating | still.
- **ShaderCanvas** (`data-slot="mesh-gradient-canvas"`) — The WebGL layer behind the children (aria-hidden).
- **Fallback** (`data-slot="mesh-gradient-fallback"`) — Layered CSS radial gradients shown when WebGL2 is unavailable.

## Accessibility

- The gradient is decorative and aria-hidden; children keep their normal semantics.
- Text on top needs contrast: use `signal`/`paper` with text-kura-fg, or a dark preset with light text, and check both themes.
- The pointer lens is purely visual; nothing is interactive about the gradient itself.
- Reduced motion: Renders a single still frame (no flow, no pointer lens). Theme changes still redraw it.

## Notes for agents

- Always give the root a size (e.g. `className="h-64 w-full rounded-kura-xl"` or `min-h-80`); it has no intrinsic height without children.
- Children render in normal flow on top — use the root as the section itself (add padding/flex), not as an absolutely positioned layer.
- Custom colours are resolved once per theme change; CSS variables work (`['var(--kura-accent)', 'oklch(0.9 0.04 90)']`).
- Pair with `<Grain />` as the last child for a print-like finish on large heroes.
- Use at most one or two animated gradients per page; give each a different `seed`.

## Examples

### Theme-aware signal gradient (minimal)

Give it a size; the default `signal` preset follows light and dark.

```tsx
import { MeshGradient } from "@kura-ui/react/mesh-gradient";

export function MeshGradientMinimal() {
  return <MeshGradient className="h-64 w-full rounded-kura-xl shadow-kura-sm" />;
}
```

### Presets and controls (full)

Every preset plus distortion, swirl, speed, grain and pause.

```tsx
"use client";

import * as React from "react";
import { Button } from "@kura-ui/react/button";
import { MeshGradient, type MeshGradientPreset } from "@kura-ui/react/mesh-gradient";

const presets: MeshGradientPreset[] = ["signal", "paper", "jade", "dusk", "ember", "glacier"];

function Slider({
  label,
  value,
  onChange,
  max = 1,
  step = 0.05,
}: {
  label: string;
  value: number;
  onChange: (v: number) => void;
  max?: number;
  step?: number;
}) {
  return (
    <label className="flex flex-col gap-1.5 text-kura-fg-muted text-xs">
      <span className="flex justify-between">
        {label}
        <span className="font-kura-mono text-kura-fg-subtle tabular-nums">{value.toFixed(2)}</span>
      </span>
      <input
        type="range"
        min={0}
        max={max}
        step={step}
        value={value}
        onChange={(e) => onChange(Number(e.target.value))}
        className="accent-kura-accent"
      />
    </label>
  );
}

export function MeshGradientFull() {
  const [preset, setPreset] = React.useState<MeshGradientPreset>("jade");
  const [distortion, setDistortion] = React.useState(0.6);
  const [swirl, setSwirl] = React.useState(0.35);
  const [speed, setSpeed] = React.useState(1);
  const [grain, setGrain] = React.useState(0.15);
  const [paused, setPaused] = React.useState(false);
  return (
    <div className="flex w-full max-w-2xl flex-col gap-4">
      <MeshGradient
        colors={preset}
        distortion={distortion}
        swirl={swirl}
        speed={speed}
        grain={grain}
        paused={paused}
        seed={2}
        className="aspect-[16/9] w-full rounded-kura-xl shadow-kura-md"
      />
      <div className="flex flex-wrap items-center gap-1.5">
        {presets.map((p) => (
          <Button
            key={p}
            size="sm"
            variant={p === preset ? "secondary" : "ghost"}
            aria-pressed={p === preset}
            onClick={() => setPreset(p)}
            className="capitalize"
          >
            {p}
          </Button>
        ))}
        <Button size="sm" variant="ghost" className="ml-auto" onClick={() => setPaused((v) => !v)}>
          {paused ? "Play" : "Pause"}
        </Button>
      </div>
      <div className="grid grid-cols-2 gap-x-6 gap-y-3 sm:grid-cols-4">
        <Slider label="Distortion" value={distortion} onChange={setDistortion} />
        <Slider label="Swirl" value={swirl} onChange={setSwirl} />
        <Slider label="Speed" value={speed} onChange={setSpeed} max={3} step={0.1} />
        <Slider label="Grain" value={grain} onChange={setGrain} />
      </div>
    </div>
  );
}
```

### Hero section (composition)

Headline, badge and Button rendered as children on top of the gradient.

```tsx
import { ArrowRight } from "lucide-react";
import { Button } from "@kura-ui/react/button";
import { MeshGradient } from "@kura-ui/react/mesh-gradient";

export function MeshGradientHero() {
  return (
    <MeshGradient
      colors="signal"
      distortion={0.7}
      swirl={0.3}
      className="flex min-h-80 w-full flex-col items-start justify-end gap-4 rounded-kura-2xl p-8 shadow-kura-md"
    >
      <span className="rounded-full bg-kura-overlay px-2.5 py-1 font-medium text-kura-accent-text text-xs shadow-kura-xs backdrop-blur-xl">
        Agents · Beta
      </span>
      <h2 className="max-w-md text-balance font-medium text-3xl text-kura-fg tracking-tight">
        Hand off the busywork. Keep the judgement.
      </h2>
      <p className="max-w-sm text-kura-fg-muted text-sm leading-relaxed">
        Kura agents read your repo, plan the change and wait for your approval before touching
        anything.
      </p>
      <Button>
        Start a run <ArrowRight />
      </Button>
    </MeshGradient>
  );
}
```

## Dependencies

- npm: none
- Kura registry items: `kura-theme`, `kura-merge-refs`, `kura-shader-color`, `shader-canvas`, `use-reduced-motion`, `utils`
- Related: `aurora`, `grain`, `shader-canvas`, `agent-orb`, `particle-field`

---

# Message

> Chat message (user/assistant) with avatar, hover actions, ‹ 2/3 › branches, error/streaming states and an autoscrolling MessageList thread.

- **Slug:** `message` · **Category:** conversation · **Status:** beta
- **Import:** `import { Message, MessageAction, MessageActions, MessageAvatar, MessageBranch, MessageCopyButton, MessageFeedback, MessageList } from "@kura-ui/react/message";`
- **Docs:** https://kuro.abstergo.fyi/components/message
- **Registry item:** https://kuro.abstergo.fyi/r/message.json
- **Tags:** chat, message, conversation, thread, bubble, autoscroll, feedback, actions

## Install

```bash
# shadcn registry (copies source into your project)
npx shadcn@latest add https://kuro.abstergo.fyi/r/message.json
# Kura CLI (same, plus dependency resolution and --json output)
npx @kura-ui/cli add message
# npm package
npm install @kura-ui/react
```

## When to use

- Render the turns of a chat with an LLM: user bubbles on the right, assistant answers as open text on the left.
- Add per-message actions: copy, regenerate, edit, thumbs up/down and navigation between regenerated versions.
- Show a failed generation with an inline error and a Retry button.
- Wrap a whole conversation in MessageList for stick-to-bottom autoscroll with a “Jump to latest” pill.

## When not to use

- Only the streaming answer text, without chrome — use streaming-text.
- A model's hidden chain of thought — put a reasoning block inside the assistant Message.
- A tool invocation or an agent plan — use tool-call or agent-timeline inside the assistant Message.
- The input box at the bottom of a chat — use composer.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `from` | `"user" \| "assistant"` | — | yes | Who wrote it. user = right-aligned gray bubble with a tucked bottom-right corner; assistant = full-width open text. |
| `name` | `React.ReactNode` | — | no | Display name in the header, e.g. "Kura" or "You". |
| `avatar` | `React.ReactNode` | — | no | Avatar element, usually `<MessageAvatar name src? fallback? />`. |
| `timestamp` | `Date \| number \| string` | — | no | Sent time. A Date/epoch renders as a localized time (“10:42 AM”) in a <time> element with the full date as title; a string renders as-is. |
| `status` | `"idle" \| "streaming" \| "error"` | `"idle"` | no | streaming: sets aria-busy and keeps the action row invisible + inert (still laid out — no shift when it appears). error: dims the content and shows `error` with an optional Retry. |
| `error` | `React.ReactNode` | `"Something went wrong."` | no | Error text for status="error". |
| `onRetry` | `() => void` | — | no | Adds a Retry button to the error row. |
| `actions` | `React.ReactNode` | — | no | Action bar under the content, usually `<MessageActions>` with MessageCopyButton, MessageAction, MessageFeedback, MessageBranch. |

Native attributes of the root element, `className` and `ref` are passed through.

## Anatomy

- **MessageList** (`data-slot="message-list"`) — Thread container (`role="log"` viewport). Sticks to the bottom while content grows, releases when the reader scrolls up, shows a “Jump to latest” pill. `data-at-bottom`.
  - `stickToBottom`: `boolean` = `true` — Follow new content while the reader is at the bottom.
  - `threshold`: `number` = `64` — Px from the bottom that still counts as at-bottom.
  - `jumpLabel`: `string` = `"Jump to latest"` — Label of the jump pill.
  - `contentClassName`: `string` — Classes for the inner column (default `flex flex-col gap-5 px-4 py-6`).
- **Message** (`data-slot="message"`) — Root. `data-from`, `data-status`, `aria-busy` while streaming.
- **Header** (`data-slot="message-header"`) — Name and time.
- **Body** (`data-slot="message-body"`) — Content slot: a flex column with gap-3, with markdown-friendly styles for p, ul/ol, a, strong, inline code, blockquote and h1–h3. Drop in rendered markdown, StreamingText or CodeBlocks.
- **Error** (`data-slot="message-error"`) — role="alert" row for status="error".
- **MessageAvatar** (`data-slot="message-avatar"`) — 28px round avatar: image → custom fallback → initials.
  - `name`: `string` — Alt text and initials source.
  - `src`: `string` — Image URL; broken images fall back.
  - `fallback`: `React.ReactNode` — Custom fallback such as a logo or lucide icon.
- **MessageActions** (`data-slot="message-actions"`) — role="group" action bar; fades in on hover/focus-within, always visible on coarse pointers.
  - `visibility`: `"hover" | "always"` = `"hover"` — Reveal on hover/focus, or always show.
- **MessageAction** (`data-slot="message-action"`) — Small labelled IconButton (tooltip included) for regenerate, edit, share…
- **MessageCopyButton** — Copy action; the icon cross-fades to a check for 1.6s and a polite status announces it.
  - `text`: `string` — Text to copy (usually the raw markdown).
  - `onCopied`: `() => void` — Called after a successful copy.
- **MessageFeedback** (`data-slot="message-feedback"`) — Thumbs up/down toggles (aria-pressed); pressing the active one clears it. `data-value`.
  - `value`: `"up" | "down" | null` — Controlled rating.
  - `defaultValue`: `"up" | "down" | null` = `null` — Initial rating when uncontrolled.
  - `onValueChange`: `(value: "up" | "down" | null) => void` — Called with the new rating.
- **MessageBranch** (`data-slot="message-branch"`) — “‹ 2/3 ›” version switcher for regenerations/edits; renders nothing when total ≤ 1.
  - `current`: `number` — 1-based visible version.
  - `total`: `number` — Number of versions.
  - `onCurrentChange`: `(current: number) => void` — Called with the new 1-based index.
- **Jump** (`data-slot="message-list-jump"`) — “Jump to latest” pill; `data-state="visible" | "hidden"` (inert when hidden).

## Accessibility

- Role: `log`
- MessageList's viewport is `role="log"` (implicitly polite) labelled “Conversation”, and focusable so the thread scrolls with the keyboard. A streaming Message sets `aria-busy`, so assistive tech announces the finished answer rather than each token.
- Every action is a labelled icon button with a tooltip; feedback toggles use aria-pressed; the branch switcher announces “Version 2 of 3”.
- Actions are revealed on hover AND keyboard focus (focus-within), and are always visible on touch devices.
- The error row is `role="alert"`.
- The hidden jump pill is inert and aria-hidden, so it never traps focus.
- Reduced motion: Jump-to-latest scrolls instantly and its pill only fades (no slide/scale); the copy check and thumbs swap without scale/blur.

| Keys | Action |
| --- | --- |
| Tab | Moves into a message's actions (revealing the bar) and through them |
| ↑ / ↓ / Page Up / Page Down | Scroll the focused thread |
| Enter / Space | Activate an action; toggle feedback |

## Notes for agents

- Give MessageList a height (h-[480px], flex-1 inside a flex column, …) — it scrolls internally.
- Use `from`, not `role`, for the author (role is the ARIA attribute).
- Set status="streaming" on the assistant Message while StreamingText is running, then "idle" in its onComplete; pass `actions` from the start so the row is reserved.
- Message renders children inside a flex column with gap-3 — pass block elements (p, CodeBlock, lists) directly; do not add margins.
- For markdown, render it to elements (react-markdown etc.) inside Message; inline code, links, lists and blockquotes are styled by the body.
- Keep MessageBranch state (current version) in your store alongside the alternative texts.

## Examples

### Two turns (minimal)

A user bubble and an assistant answer.

```tsx
import { Message } from "@kura-ui/react/message";

export function MessageMinimal() {
  return (
    <div className="flex w-full max-w-xl flex-col gap-4">
      <Message from="user">How do I make a like button feel instant?</Message>
      <Message from="assistant">
        Render the new count optimistically and reconcile when the request finishes.
      </Message>
    </div>
  );
}
```

### Avatars, actions and versions (full)

Name, time, avatar, copy/regenerate/edit, controlled thumbs, ‹ 2/3 › branches. Regenerate simulates an error with Retry.

```tsx
"use client";

import { Pencil, RefreshCw } from "lucide-react";
import * as React from "react";
import {
  Message,
  MessageAction,
  MessageActions,
  MessageAvatar,
  MessageBranch,
  MessageCopyButton,
  MessageFeedback,
} from "@kura-ui/react/message";

const VERSIONS = [
  "Use `useOptimistic` for the like button: render the optimistic count immediately, then reconcile when the server action resolves.",
  "Wrap the mutation in a transition and render from `useOptimistic`. If the action throws, React drops the optimistic value and the real count comes back on its own.",
  "Keep it simple: update local state on click, call the server action, and roll back in a `catch`. `useOptimistic` saves you that rollback.",
];

export function MessageFull() {
  const [version, setVersion] = React.useState(2);
  const [rating, setRating] = React.useState<"up" | "down" | null>("up");
  const [failed, setFailed] = React.useState(false);
  const text = VERSIONS[version - 1]!;
  return (
    <div className="flex w-full max-w-xl flex-col gap-4">
      <Message
        from="user"
        name="You"
        timestamp="10:41"
        avatar={<MessageAvatar name="Ada Lovelace" />}
        actions={
          <MessageActions>
            <MessageAction label="Edit" icon={<Pencil />} />
            <MessageCopyButton text="Why does my like button lag?" />
          </MessageActions>
        }
      >
        Why does my like button lag?
      </Message>
      <Message
        from="assistant"
        name="Kura"
        timestamp="10:42"
        avatar={<MessageAvatar name="Kura" />}
        status={failed ? "error" : "idle"}
        error="The model stopped responding. Partial answer shown."
        onRetry={() => setFailed(false)}
        actions={
          <MessageActions visibility="always">
            <MessageCopyButton text={text} />
            <MessageAction
              label="Regenerate"
              icon={<RefreshCw />}
              onClick={() => setFailed(true)}
            />
            <MessageFeedback value={rating} onValueChange={setRating} />
            <MessageBranch current={version} total={VERSIONS.length} onCurrentChange={setVersion} />
          </MessageActions>
        }
      >
        <p key={version} className="animate-kura-fade-in">
          {text.split("`").map((part, i) => (i % 2 ? <code key={i}>{part}</code> : part))}
        </p>
      </Message>
    </div>
  );
}
```

### Streaming and error (state)

A streaming answer with reserved actions, and a failed one.

```tsx
"use client";

import * as React from "react";
import { StreamingText } from "@kura-ui/react/streaming-text";
import { Message, MessageActions, MessageAvatar, MessageCopyButton } from "@kura-ui/react/message";

async function* tokens(text: string): AsyncGenerator<string> {
  const words = text.split(/(?<=\s)/);
  for (let i = 0; i < words.length; ) {
    const n = 1 + Math.floor(Math.random() * 3);
    yield words.slice(i, i + n).join("");
    i += n;
    await new Promise((r) => setTimeout(r, 30 + Math.random() * 110));
  }
}

export function MessageStates() {
  const [stream] = React.useState(() =>
    tokens(
      "Reading the trace now. The slow part is the waterfall: the like request waits on the session refresh, so the button cannot update until both finish.",
    ),
  );
  return (
    <div className="flex w-full max-w-xl flex-col gap-4">
      <Message
        from="assistant"
        name="Kura"
        avatar={<MessageAvatar name="Kura" />}
        status="streaming"
        actions={
          <MessageActions>
            <MessageCopyButton text="" />
          </MessageActions>
        }
      >
        <StreamingText stream={stream} />
      </Message>
      <Message
        from="assistant"
        name="Kura"
        avatar={<MessageAvatar name="Kura" />}
        status="error"
        error="Rate limited — try again in a few seconds."
        onRetry={() => {}}
      >
        I started profiling the
      </Message>
    </div>
  );
}
```

### Autoscrolling thread (composition)

MessageList with StreamingText, CodeBlock and a shimmering “Thinking…” turn. Scroll up mid-stream to see “Jump to latest”.

```tsx
"use client";

import { ArrowUp, RefreshCw } from "lucide-react";
import * as React from "react";
import { Button } from "@kura-ui/react/button";
import { CodeBlock } from "@kura-ui/react/code-block";
import { ShimmerText } from "@kura-ui/react/shimmer-text";
import { StreamingText } from "@kura-ui/react/streaming-text";
import { Message, MessageAction, MessageActions, MessageAvatar, MessageCopyButton, MessageFeedback } from "@kura-ui/react/message";
import { MessageList } from "@kura-ui/react/message";

async function* tokens(text: string): AsyncGenerator<string> {
  const words = text.split(/(?<=\s)/);
  for (let i = 0; i < words.length; ) {
    const n = 1 + Math.floor(Math.random() * 3);
    yield words.slice(i, i + n).join("");
    i += n;
    await new Promise((r) => setTimeout(r, 30 + Math.random() * 110));
  }
}

const LONG_ANSWER =
  "Three things will make the thread feel calm.\n\nFirst, stick to the bottom only while the reader is there. The moment they scroll up, stop following — nothing is worse than being yanked back mid-sentence.\n\nSecond, reserve space for things that appear later, like the action bar, so the end of a stream never shifts the layout.\n\nThird, announce the finished message, not every token: the log is `aria-busy` while the answer streams.";

export function MessageThread() {
  const [turns, setTurns] = React.useState<Turn[]>([
    { id: 1, from: "user", text: "Can you review the chat layout?" },
    {
      id: 2,
      from: "assistant",
      text: "Sure. The structure is solid; two details stand out. The composer jumps when the keyboard opens on iOS, and new messages push the reader down even when they are reading older ones.",
    },
    { id: 3, from: "user", text: "Show me the fix for the composer." },
    { id: 4, from: "assistant", text: "Pin it with dynamic viewport units:" },
  ]);
  const [streaming, setStreaming] = React.useState<number | null>(null);
  const [waiting, setWaiting] = React.useState(false);

  const ask = () => {
    const id = Date.now();
    setTurns((t) => [...t, { id, from: "user", text: "How should the thread scroll?" }]);
    setWaiting(true);
    setTimeout(() => {
      setWaiting(false);
      setStreaming(id + 1);
      setTurns((t) => [
        ...t,
        { id: id + 1, from: "assistant", text: "", stream: tokens(LONG_ANSWER) },
      ]);
    }, 900);
  };

  return (
    <div className="flex h-[440px] w-full max-w-xl flex-col overflow-hidden rounded-kura-xl bg-kura-surface shadow-kura-sm">
      <MessageList className="flex-1" contentClassName="px-5">
        {turns.map((turn) => (
          <Message
            key={turn.id}
            from={turn.from}
            status={streaming === turn.id ? "streaming" : "idle"}
            avatar={turn.from === "assistant" ? <MessageAvatar name="Kura" /> : undefined}
            actions={
              turn.from === "assistant" ? (
                <MessageActions>
                  <MessageCopyButton text={turn.text} />
                  <MessageAction label="Regenerate" icon={<RefreshCw />} />
                  <MessageFeedback />
                </MessageActions>
              ) : undefined
            }
          >
            {turn.stream ? (
              <StreamingText stream={turn.stream} onComplete={() => setStreaming(null)} />
            ) : (
              turn.text
            )}
            {turn.id === 4 && (
              <CodeBlock
                language="css"
                filename="composer.css"
                code={".composer {\n  position: sticky;\n  bottom: 0;\n  max-height: 40dvh;\n}"}
              />
            )}
          </Message>
        ))}
        {waiting && (
          <Message from="assistant" avatar={<MessageAvatar name="Kura" />} status="streaming">
            <ShimmerText>Thinking…</ShimmerText>
          </Message>
        )}
      </MessageList>
      <div className="flex items-center justify-between gap-3 px-4 py-3 shadow-[inset_0_1px_0_var(--kura-border-subtle)]">
        <span className="text-kura-fg-subtle text-xs">Scroll up while it streams.</span>
        <Button size="sm" onClick={ask} disabled={waiting || streaming !== null}>
          Ask a follow-up <ArrowUp />
        </Button>
      </div>
    </div>
  );
}
```

## Dependencies

- npm: `lucide-react`
- Kura registry items: `kura-theme`, `button`, `icon-button`, `use-controllable-state`, `use-reduced-motion`, `utils`
- Related: `streaming-text`, `code-block`, `reasoning`, `tool-call`, `citation`, `composer`

---

# Model Picker

> Searchable popover for choosing an AI model, grouped by provider, with capability icons, context size, speed and cost hints.

- **Slug:** `model-picker` · **Category:** input · **Status:** beta
- **Import:** `import { ModelCapability, ModelPicker, ModelPickerModel } from "@kura-ui/react/model-picker";`
- **Docs:** https://kuro.abstergo.fyi/components/model-picker
- **Registry item:** https://kuro.abstergo.fyi/r/model-picker.json
- **Tags:** model, llm, select, combobox, picker, provider, dropdown

## Install

```bash
# shadcn registry (copies source into your project)
npx shadcn@latest add https://kuro.abstergo.fyi/r/model-picker.json
# Kura CLI (same, plus dependency resolution and --json output)
npx @kura-ui/cli add model-picker
# npm package
npm install @kura-ui/react
```

## When to use

- Let the user switch the model in a chat composer toolbar or a chat header.
- Compare models at a glance: vision/tools/reasoning support, context window, speed and price tier.
- Any “choose one of N models/agents/providers” selector that benefits from search and grouping.

## When not to use

- Running actions or navigating — use command-palette.
- Inserting commands while typing a prompt — use slash-command-menu.
- Two or three static options without metadata — a segmented control or plain select is enough.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `models` | `readonly ModelPickerModel[]` | — | yes | Models: { id, name, provider?, description?, capabilities?, contextWindow?, speed?: 1\|2\|3, cost?: 1\|2\|3, badge?, disabled?, icon? }. Grouped by provider in first-seen order. |
| `value` | `string` | — | no | Controlled selected model id. |
| `defaultValue` | `string` | — | no | Initial id when uncontrolled. Defaults to the first enabled model. |
| `onValueChange` | `(id: string, model: ModelPickerModel) => void` | — | no | Called when the user picks a model. |
| `open` | `boolean` | — | no | Controlled open state. |
| `defaultOpen` | `boolean` | `false` | no | Initial open state. |
| `onOpenChange` | `(open: boolean) => void` | — | no | Open state changes. |
| `searchable` | `boolean` | — | no | Show the search field. Default: true when there are more than 6 models. |
| `placeholder` | `string` | `"Select model"` | no | Trigger text when nothing is selected. |
| `searchPlaceholder` | `string` | `"Search models…"` | no | Search field placeholder. |
| `emptyMessage` | `string` | `"No models match"` | no | Shown when the search has no results. |
| `showDetails` | `boolean` | `true` | no | Fixed-height footer describing the highlighted model (no layout shift). |
| `side` | `"top" \| "bottom"` | `"bottom"` | no | Preferred popover side; flips on collision. Use top in a bottom-docked composer. |
| `align` | `"start" \| "center" \| "end"` | `"start"` | no | Popover alignment relative to the trigger. |
| `size` | `"sm" \| "md"` | `"sm"` | no | Trigger height: sm 32px for toolbars, md 36px. |

Native attributes of the root element, `className` and `ref` are passed through.

## Anatomy

- **ModelPicker** (`data-slot="model-picker"`) — The trigger button (provider mark, model name, chevron). data-state = open | closed.
- **ModelPickerContent** (`data-slot="model-picker-content"`) — Popover surface; scales from the trigger (origin-aware).
- **ModelPickerSearch** (`data-slot="model-picker-search"`) — Search row; the input is the combobox that owns keyboard navigation.
- **ModelPickerGroup** (`data-slot="model-picker-group"`) — role=group per provider, labelled by its heading.
- **ModelPickerItem** (`data-slot="model-picker-item"`) — role=option row: name, badge, meta line, capability icons, check. data-active, data-disabled.
- **ModelPickerDetails** (`data-slot="model-picker-details"`) — Footer with the highlighted model's description.

## Accessibility

- Role: `combobox + listbox`
- The trigger is labelled “Model: <name>”. On open, focus moves to the search combobox (or the listbox when not searchable) and returns to the trigger on close.
- Highlighting uses aria-activedescendant, so focus never leaves the search field while navigating.
- Options expose aria-selected and aria-disabled; provider groups are role=group with their heading as label.
- Capability icons, speed and cost meters carry visually hidden text (“Vision”, “Fast”, “High cost”), so the meta line reads naturally.
- Reduced motion: The popover fades without scale or travel and the chevron flips without rotating; highlight changes are instant in all modes.

| Keys | Action |
| --- | --- |
| Enter / Space / ArrowDown | Open from the trigger |
| ArrowDown / ArrowUp | Move the highlight (wraps, skips disabled models) |
| Home / End | First / last model (when the search is empty) |
| Enter | Choose the highlighted model and close |
| Escape | Close and return focus to the trigger |

## Notes for agents

- Pass `side="top"` inside a composer docked to the bottom of the viewport.
- speed: 3 = fast, 1 = slow/thorough. cost: 1 = cheap, 3 = expensive. Omit either to hide it.
- `icon` takes a 16px provider logo; without it a monogram of the provider is shown.
- formatContextWindow(200000) → "200K" is exported for use elsewhere (e.g. a context-meter).

## Examples

### Three models (minimal)

```tsx
import { ModelPicker, type ModelPickerModel } from "@kura-ui/react/model-picker";

const models: ModelPickerModel[] = [
  {
    id: "claude-opus-5-5",
    name: "Claude Opus 5.5",
    provider: "Anthropic",
    description: "Most capable. Long-horizon agentic work, deep research and hard code.",
    capabilities: ["vision", "tools", "reasoning", "files"],
    contextWindow: 1_000_000,
    speed: 1,
    cost: 3,
    badge: "New",
  },
  {
    id: "claude-sonnet-5-5",
    name: "Claude Sonnet 5.5",
    provider: "Anthropic",
    description: "The everyday default. Strong reasoning at a fraction of the latency.",
    capabilities: ["vision", "tools", "reasoning", "files"],
    contextWindow: 1_000_000,
    speed: 2,
    cost: 2,
  },
  {
    id: "claude-haiku-4-5",
    name: "Claude Haiku 4.5",
    provider: "Anthropic",
    description: "Fastest. Great for classification, extraction and sub-agents.",
    capabilities: ["vision", "tools"],
    contextWindow: 200_000,
    speed: 3,
    cost: 1,
  },
  {
    id: "gpt-5",
    name: "GPT-5",
    provider: "OpenAI",
    description: "General-purpose flagship with adjustable reasoning effort.",
    capabilities: ["vision", "tools", "reasoning", "web"],
    contextWindow: 400_000,
    speed: 2,
    cost: 2,
  },
  {
    id: "gpt-5-mini",
    name: "GPT-5 mini",
    provider: "OpenAI",
    description: "Smaller and cheaper, tuned for well-defined tasks.",
    capabilities: ["vision", "tools"],
    contextWindow: 400_000,
    speed: 3,
    cost: 1,
  },
  {
    id: "gemini-2-5-pro",
    name: "Gemini 2.5 Pro",
    provider: "Google",
    description: "Native audio and video understanding with a very long context.",
    capabilities: ["vision", "audio", "tools", "reasoning"],
    contextWindow: 1_000_000,
    speed: 2,
    cost: 2,
  },
  {
    id: "llama-4-maverick",
    name: "Llama 4 Maverick",
    provider: "Open weights",
    description: "Self-hostable mixture-of-experts model.",
    capabilities: ["vision"],
    contextWindow: 1_000_000,
    speed: 3,
    cost: 1,
  },
  {
    id: "mistral-large",
    name: "Mistral Large",
    provider: "Open weights",
    description: "Unavailable on the free plan.",
    capabilities: ["tools"],
    contextWindow: 128_000,
    speed: 2,
    cost: 2,
    badge: "Pro",
    disabled: true,
  },
];

export function ModelPickerMinimal() {
  return <ModelPicker models={models.slice(0, 3)} />;
}
```

### Searchable, grouped, controlled (full)

Eight models across providers, a disabled tier, badges, capability icons and a controlled open state.

```tsx
"use client";

import * as React from "react";
import { ModelPicker, type ModelPickerModel } from "@kura-ui/react/model-picker";

const models: ModelPickerModel[] = [
  {
    id: "claude-opus-5-5",
    name: "Claude Opus 5.5",
    provider: "Anthropic",
    description: "Most capable. Long-horizon agentic work, deep research and hard code.",
    capabilities: ["vision", "tools", "reasoning", "files"],
    contextWindow: 1_000_000,
    speed: 1,
    cost: 3,
    badge: "New",
  },
  {
    id: "claude-sonnet-5-5",
    name: "Claude Sonnet 5.5",
    provider: "Anthropic",
    description: "The everyday default. Strong reasoning at a fraction of the latency.",
    capabilities: ["vision", "tools", "reasoning", "files"],
    contextWindow: 1_000_000,
    speed: 2,
    cost: 2,
  },
  {
    id: "claude-haiku-4-5",
    name: "Claude Haiku 4.5",
    provider: "Anthropic",
    description: "Fastest. Great for classification, extraction and sub-agents.",
    capabilities: ["vision", "tools"],
    contextWindow: 200_000,
    speed: 3,
    cost: 1,
  },
  {
    id: "gpt-5",
    name: "GPT-5",
    provider: "OpenAI",
    description: "General-purpose flagship with adjustable reasoning effort.",
    capabilities: ["vision", "tools", "reasoning", "web"],
    contextWindow: 400_000,
    speed: 2,
    cost: 2,
  },
  {
    id: "gpt-5-mini",
    name: "GPT-5 mini",
    provider: "OpenAI",
    description: "Smaller and cheaper, tuned for well-defined tasks.",
    capabilities: ["vision", "tools"],
    contextWindow: 400_000,
    speed: 3,
    cost: 1,
  },
  {
    id: "gemini-2-5-pro",
    name: "Gemini 2.5 Pro",
    provider: "Google",
    description: "Native audio and video understanding with a very long context.",
    capabilities: ["vision", "audio", "tools", "reasoning"],
    contextWindow: 1_000_000,
    speed: 2,
    cost: 2,
  },
  {
    id: "llama-4-maverick",
    name: "Llama 4 Maverick",
    provider: "Open weights",
    description: "Self-hostable mixture-of-experts model.",
    capabilities: ["vision"],
    contextWindow: 1_000_000,
    speed: 3,
    cost: 1,
  },
  {
    id: "mistral-large",
    name: "Mistral Large",
    provider: "Open weights",
    description: "Unavailable on the free plan.",
    capabilities: ["tools"],
    contextWindow: 128_000,
    speed: 2,
    cost: 2,
    badge: "Pro",
    disabled: true,
  },
];

export function ModelPickerFull() {
  const [model, setModel] = React.useState("claude-sonnet-5-5");
  const [open, setOpen] = React.useState(false);
  const current = models.find((m) => m.id === model);
  return (
    <div className="flex flex-col items-center gap-3">
      <ModelPicker
        models={models}
        value={model}
        onValueChange={(id) => setModel(id)}
        open={open}
        onOpenChange={setOpen}
        searchable
        size="md"
        side="bottom"
        align="center"
        placeholder="Choose a model"
        searchPlaceholder="Search by name, provider or capability…"
        emptyMessage="No model has that capability"
        showDetails
      />
      <p className="text-kura-fg-subtle text-xs" aria-live="polite">
        Using <span className="font-kura-mono text-kura-fg-muted">{current?.id}</span>
      </p>
    </div>
  );
}
```

### In a composer toolbar (composition)

Opens upward from the composer's toolbar.

```tsx
"use client";

import * as React from "react";
import {
  Composer,
  ComposerActions,
  ComposerAttachButton,
  ComposerInput,
  ComposerSubmit,
  ComposerToolbar,
  ComposerTools,
} from "@kura-ui/react/composer";
import { ModelPicker, type ModelPickerModel } from "@kura-ui/react/model-picker";

const models: ModelPickerModel[] = [
  {
    id: "claude-opus-5-5",
    name: "Claude Opus 5.5",
    provider: "Anthropic",
    description: "Most capable. Long-horizon agentic work, deep research and hard code.",
    capabilities: ["vision", "tools", "reasoning", "files"],
    contextWindow: 1_000_000,
    speed: 1,
    cost: 3,
    badge: "New",
  },
  {
    id: "claude-sonnet-5-5",
    name: "Claude Sonnet 5.5",
    provider: "Anthropic",
    description: "The everyday default. Strong reasoning at a fraction of the latency.",
    capabilities: ["vision", "tools", "reasoning", "files"],
    contextWindow: 1_000_000,
    speed: 2,
    cost: 2,
  },
  {
    id: "claude-haiku-4-5",
    name: "Claude Haiku 4.5",
    provider: "Anthropic",
    description: "Fastest. Great for classification, extraction and sub-agents.",
    capabilities: ["vision", "tools"],
    contextWindow: 200_000,
    speed: 3,
    cost: 1,
  },
  {
    id: "gpt-5",
    name: "GPT-5",
    provider: "OpenAI",
    description: "General-purpose flagship with adjustable reasoning effort.",
    capabilities: ["vision", "tools", "reasoning", "web"],
    contextWindow: 400_000,
    speed: 2,
    cost: 2,
  },
  {
    id: "gpt-5-mini",
    name: "GPT-5 mini",
    provider: "OpenAI",
    description: "Smaller and cheaper, tuned for well-defined tasks.",
    capabilities: ["vision", "tools"],
    contextWindow: 400_000,
    speed: 3,
    cost: 1,
  },
  {
    id: "gemini-2-5-pro",
    name: "Gemini 2.5 Pro",
    provider: "Google",
    description: "Native audio and video understanding with a very long context.",
    capabilities: ["vision", "audio", "tools", "reasoning"],
    contextWindow: 1_000_000,
    speed: 2,
    cost: 2,
  },
  {
    id: "llama-4-maverick",
    name: "Llama 4 Maverick",
    provider: "Open weights",
    description: "Self-hostable mixture-of-experts model.",
    capabilities: ["vision"],
    contextWindow: 1_000_000,
    speed: 3,
    cost: 1,
  },
  {
    id: "mistral-large",
    name: "Mistral Large",
    provider: "Open weights",
    description: "Unavailable on the free plan.",
    capabilities: ["tools"],
    contextWindow: 128_000,
    speed: 2,
    cost: 2,
    badge: "Pro",
    disabled: true,
  },
];

export function ModelPickerInComposer() {
  const [model, setModel] = React.useState("claude-opus-5-5");
  return (
    <div className="w-full max-w-xl">
      <Composer onSubmit={() => {}}>
        <ComposerInput placeholder="Plan a migration from REST to GraphQL…" />
        <ComposerToolbar>
          <ComposerTools>
            <ComposerAttachButton />
            <ModelPicker models={models} value={model} onValueChange={setModel} side="top" />
          </ComposerTools>
          <ComposerActions>
            <ComposerSubmit />
          </ComposerActions>
        </ComposerToolbar>
      </Composer>
    </div>
  );
}
```

## Dependencies

- npm: `lucide-react`
- Kura registry items: `kura-theme`, `popover`, `use-controllable-state`, `utils`
- Related: `composer`, `command-palette`, `slash-command-menu`

---

# Particle Field

> Drifting particle constellation that parts around the pointer and can converge into a ring or point to signal “generating”.

- **Slug:** `particle-field` · **Category:** effects · **Status:** beta
- **Import:** `import { ParticleField } from "@kura-ui/react/particle-field";`
- **Docs:** https://kuro.abstergo.fyi/components/particle-field
- **Registry item:** https://kuro.abstergo.fyi/r/particle-field.json
- **Tags:** particles, constellation, network, canvas, background, generating, interactive

## Install

```bash
# shadcn registry (copies source into your project)
npx shadcn@latest add https://kuro.abstergo.fyi/r/particle-field.json
# Kura CLI (same, plus dependency resolution and --json output)
npx @kura-ui/cli add particle-field
# npm package
npm install @kura-ui/react
```

## When to use

- An empty state or hero for a knowledge/graph/agent product where a quiet network motif fits.
- Signalling that something is being generated: flip `converge` while the model works, release when done.
- A subtle, interactive backdrop behind a short prompt or call to action.

## When not to use

- Soft colour backgrounds — use mesh-gradient or aurora.
- Inline progress feedback — use thinking-indicator or shimmer-text.
- A voice agent's presence — use agent-orb.
- Behind dense content: lines and motion compete with text.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `count` | `number` | — | no | Number of particles. Default scales with the area (≈ one per 5,500 px², clamped 30–160). Links are O(n²); stay under ~180. |
| `linkDistance` | `number` | `110` | no | Max px distance at which two particles are joined by a hairline. |
| `speed` | `number` | `1` | no | Drift speed multiplier. |
| `interactive` | `boolean` | `true` | no | Particles part around the pointer and link to it in the accent colour. |
| `converge` | `boolean` | `false` | no | Gather the particles into `shape` in the accent colour (the generating signal). Set false to release them back into a drift. |
| `shape` | `"ring" \| "point"` | `"ring"` | no | ring: a slowly turning halo. point: a tight orbiting cluster. |
| `paused` | `boolean` | `false` | no | Freeze the field on the current frame. |
| `maxDpr` | `number` | `2` | no | Device-pixel-ratio cap. |
| `children` | `React.ReactNode` | — | no | Content rendered on top, in normal flow. |

Native attributes of the root element, `className` and `ref` are passed through.

## Anatomy

- **ParticleField** (`data-slot="particle-field"`) — Root (`relative isolate overflow-hidden text-kura-fg-subtle`). `data-state` = drifting | converging | still | fallback; `data-converge` mirrors the prop.
- **Canvas** (`data-slot="particle-field-canvas"`) — The 2D canvas behind the children (aria-hidden).
- **Fallback** (`data-slot="particle-field-fallback"`) — A static CSS dot grid shown when canvas 2D is unavailable.

## Accessibility

- Decorative: the canvas is aria-hidden and never takes pointer events from children.
- Converging is a visual signal only — pair it with text in a role=status region (e.g. “Generating…”).
- Reduced motion: No drift, travel or pointer reaction: one still frame. Toggling `converge` jumps straight to the gathered (or scattered) layout without animating.

## Notes for agents

- Particle and link colour = the root's text colour; recolour with a class (`text-kura-fg-muted`). Converged particles and pointer links use `--kura-accent`.
- Give the root a height and a background; the canvas is transparent.
- Use `converge` for indeterminate generation (seconds, not milliseconds) and release it when output appears.
- It pauses automatically offscreen; keep one field per view.

## Examples

### Drifting constellation (minimal)

Size it and give it a background; particles use the text colour.

```tsx
import { ParticleField } from "@kura-ui/react/particle-field";

export function ParticleFieldMinimal() {
  return (
    <ParticleField className="h-64 w-full rounded-kura-xl bg-kura-surface-sunken shadow-kura-sm" />
  );
}
```

### Converge, shapes and pause (full)

Toggle converge, switch ring/point, tune link distance and speed.

```tsx
"use client";

import * as React from "react";
import { Button } from "@kura-ui/react/button";
import { ParticleField, type ParticleFieldShape } from "@kura-ui/react/particle-field";

export function ParticleFieldFull() {
  const [converge, setConverge] = React.useState(false);
  const [shape, setShape] = React.useState<ParticleFieldShape>("ring");
  const [paused, setPaused] = React.useState(false);
  return (
    <div className="flex w-full max-w-2xl flex-col gap-4">
      <ParticleField
        converge={converge}
        shape={shape}
        paused={paused}
        linkDistance={120}
        speed={1.2}
        className="aspect-[16/9] w-full rounded-kura-xl bg-kura-surface-sunken text-kura-fg-muted shadow-kura-md"
      />
      <div className="flex flex-wrap items-center gap-1.5">
        <Button
          size="sm"
          variant={converge ? "accent" : "secondary"}
          aria-pressed={converge}
          onClick={() => setConverge((c) => !c)}
        >
          {converge ? "Release" : "Converge"}
        </Button>
        {(["ring", "point"] as const).map((s) => (
          <Button
            key={s}
            size="sm"
            variant={s === shape ? "secondary" : "ghost"}
            aria-pressed={s === shape}
            onClick={() => setShape(s)}
            className="capitalize"
          >
            {s}
          </Button>
        ))}
        <Button size="sm" variant="ghost" className="ml-auto" onClick={() => setPaused((p) => !p)}>
          {paused ? "Play" : "Pause"}
        </Button>
      </div>
    </div>
  );
}
```

### Generating state (composition)

A Button starts a 4s generation: particles gather into a ring while ShimmerText reports progress.

```tsx
"use client";

import * as React from "react";
import { Button } from "@kura-ui/react/button";
import { ShimmerText } from "@kura-ui/react/shimmer-text";
import { ParticleField } from "@kura-ui/react/particle-field";

export function ParticleFieldGenerating() {
  const [generating, setGenerating] = React.useState(false);
  React.useEffect(() => {
    if (!generating) return;
    const id = setTimeout(() => setGenerating(false), 4000);
    return () => clearTimeout(id);
  }, [generating]);
  return (
    <ParticleField
      converge={generating}
      className="flex h-80 w-full flex-col items-center justify-center gap-3 rounded-kura-2xl bg-kura-surface text-center shadow-kura-md"
    >
      <div role="status" aria-live="polite" className="h-6 text-sm">
        {generating ? (
          <ShimmerText>Generating your workspace…</ShimmerText>
        ) : (
          <span className="text-kura-fg-muted">Describe a workspace and Kura sets it up.</span>
        )}
      </div>
      <Button onClick={() => setGenerating(true)} disabled={generating}>
        Generate
      </Button>
    </ParticleField>
  );
}
```

## Dependencies

- npm: none
- Kura registry items: `kura-theme`, `kura-merge-refs`, `use-reduced-motion`, `utils`
- Related: `mesh-gradient`, `aurora`, `thinking-indicator`, `agent-orb`, `grain`

---

# Popover

> Floating translucent panel anchored to a trigger, with focus management and origin-aware motion.

- **Slug:** `popover` · **Category:** primitives · **Status:** stable
- **Import:** `import { Popover, PopoverAnchor, PopoverClose, PopoverContent, PopoverTrigger } from "@kura-ui/react/popover";`
- **Docs:** https://kuro.abstergo.fyi/components/popover
- **Registry item:** https://kuro.abstergo.fyi/r/popover.json
- **Tags:** popover, overlay, floating, panel, menu, dropdown

## Install

```bash
# shadcn registry (copies source into your project)
npx shadcn@latest add https://kuro.abstergo.fyi/r/popover.json
# Kura CLI (same, plus dependency resolution and --json output)
npx @kura-ui/cli add popover
# npm package
npm install @kura-ui/react
```

## When to use

- Small interactive panels: settings for a composer, a model's details, a share menu, a filter form.
- Content anchored to a control that should not navigate away.

## When not to use

- Plain hover labels — use tooltip.
- Choosing a model — use model-picker. Slash commands — use slash-command-menu. Global search — use command-palette.
- Blocking decisions — use a dialog or approval-prompt.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `open` | `boolean` | — | no | Controlled open state. |
| `defaultOpen` | `boolean` | — | no | Initial open state when uncontrolled. |
| `onOpenChange` | `(open: boolean) => void` | — | no | Called when the open state changes. |
| `modal` | `boolean` | `false` | no | Trap focus and block outside interaction. |

Native attributes of the root element, `className` and `ref` are passed through.

## Anatomy

- **Popover** (`data-slot="popover"`) — Root; owns open state.
- **PopoverTrigger** (`data-slot="popover-trigger"`) — Toggles the popover. Use asChild with a Button.
- **PopoverAnchor** (`data-slot="popover-anchor"`) — Optional alternative positioning anchor.
- **PopoverContent** (`data-slot="popover-content"`) — The floating panel (portalled). Accepts side, align, sideOffset.
  - `inline`: `boolean` = `false` — Render without a portal (inside dialogs).
- **PopoverClose** (`data-slot="popover-close"`) — Closes the popover. Use asChild with a Button.

## Accessibility

- Role: `dialog`
- Trigger gets aria-expanded and aria-controls; focus moves into the content on open and returns on close.
- Give the content an accessible name (aria-label or a heading with aria-labelledby).
- Reduced motion: Scale and travel are removed; content fades.

| Keys | Action |
| --- | --- |
| Enter / Space | Toggle from the trigger |
| Escape | Close and return focus |
| Tab | Move through content |

## Notes for agents

- Always use `<PopoverTrigger asChild><Button …/></PopoverTrigger>` to avoid nested buttons.

## Examples

### Basic (minimal)

```tsx
import { Button } from "@kura-ui/react/button";
import { Popover, PopoverContent, PopoverTrigger } from "@kura-ui/react/popover";

export function PopoverMinimal() {
  return (
    <Popover>
      <PopoverTrigger asChild>
        <Button variant="secondary">Open</Button>
      </PopoverTrigger>
      <PopoverContent aria-label="About">Popovers hold small, interactive panels.</PopoverContent>
    </Popover>
  );
}
```

### Controlled settings panel (full)

```tsx
"use client";

import { Settings2 } from "lucide-react";
import * as React from "react";
import { Button } from "@kura-ui/react/button";
import { Popover, PopoverClose, PopoverContent, PopoverTrigger } from "@kura-ui/react/popover";

export function PopoverFull() {
  const [open, setOpen] = React.useState(false);
  const [temperature, setTemperature] = React.useState(0.7);
  return (
    <Popover open={open} onOpenChange={setOpen}>
      <PopoverTrigger asChild>
        <Button variant="secondary">
          <Settings2 /> Generation settings
        </Button>
      </PopoverTrigger>
      <PopoverContent
        side="bottom"
        align="start"
        aria-labelledby="gen-settings-title"
        className="w-64"
      >
        <div className="flex flex-col gap-3">
          <h3 id="gen-settings-title" className="font-medium text-sm">
            Generation
          </h3>
          <label className="flex flex-col gap-1.5 text-kura-fg-muted text-xs">
            <span className="flex justify-between">
              Temperature{" "}
              <span className="text-kura-fg tabular-nums">{temperature.toFixed(1)}</span>
            </span>
            <input
              type="range"
              min={0}
              max={2}
              step={0.1}
              value={temperature}
              onChange={(e) => setTemperature(Number(e.target.value))}
              className="accent-kura-accent"
            />
          </label>
          <PopoverClose asChild>
            <Button size="sm">Done</Button>
          </PopoverClose>
        </div>
      </PopoverContent>
    </Popover>
  );
}
```

### Share a chat (composition)

A chat header whose Share button opens a visibility picker and a copy-link row.

```tsx
"use client";

import { Check, Globe, Link, Lock, Share } from "lucide-react";
import * as React from "react";
import { Button } from "@kura-ui/react/button";
import { Popover, PopoverContent, PopoverTrigger } from "@kura-ui/react/popover";

const visibilityOptions = [
  {
    id: "private",
    label: "Only you",
    description: "Nobody else can open this chat.",
    icon: <Lock />,
  },
  {
    id: "link",
    label: "Anyone with the link",
    description: "Can read the chat, not continue it.",
    icon: <Globe />,
  },
] as const;

export function PopoverShareChat() {
  const [visibility, setVisibility] = React.useState<Visibility>("private");
  const [copied, setCopied] = React.useState(false);
  const timer = React.useRef<ReturnType<typeof setTimeout>>(undefined);
  React.useEffect(() => () => clearTimeout(timer.current), []);
  const shared = visibility === "link";

  return (
    <div className="flex w-full max-w-xl items-center justify-between gap-4 rounded-kura-xl bg-kura-surface py-2.5 pr-2.5 pl-4 shadow-kura-sm">
      <div className="flex min-w-0 flex-col">
        <h3 className="truncate font-medium text-kura-fg text-sm">Q3 churn analysis</h3>
        <p className="truncate text-kura-fg-subtle text-xs">
          14 messages · {shared ? "Shared with link" : "Private"}
        </p>
      </div>
      <Popover onOpenChange={(open) => !open && setCopied(false)}>
        <PopoverTrigger asChild>
          <Button variant="secondary" size="sm">
            {shared ? <Globe /> : <Share />}
            Share
          </Button>
        </PopoverTrigger>
        <PopoverContent align="end" aria-labelledby="share-chat-title" className="w-80 p-0">
          <div className="flex flex-col gap-3 p-3">
            <div className="flex flex-col gap-0.5 px-1 pt-0.5">
              <h4 id="share-chat-title" className="font-medium text-sm">
                Share this chat
              </h4>
              <p className="text-kura-fg-muted text-xs">
                Messages you send after sharing stay private.
              </p>
            </div>
            <fieldset className="flex flex-col gap-0.5">
              <legend className="sr-only">Who can view</legend>
              {visibilityOptions.map((option) => (
                <label
                  key={option.id}
                  className="group flex cursor-pointer items-center gap-3 rounded-kura-md p-2 transition-colors duration-(--kura-duration-fast) ease-kura-out hover:bg-kura-hover has-checked:bg-kura-active has-focus-visible:shadow-kura-focus"
                >
                  <input
                    type="radio"
                    name="share-visibility"
                    value={option.id}
                    checked={visibility === option.id}
                    onChange={() => setVisibility(option.id)}
                    className="sr-only"
                  />
                  <span className="flex size-8 shrink-0 items-center justify-center rounded-kura-sm bg-kura-surface text-kura-fg-muted shadow-kura-xs group-has-checked:text-kura-fg [&_svg]:size-4">
                    {option.icon}
                  </span>
                  <span className="flex min-w-0 flex-1 flex-col">
                    <span className="font-medium text-[13px] text-kura-fg">{option.label}</span>
                    <span className="text-kura-fg-muted text-xs">{option.description}</span>
                  </span>
                  <Check
                    aria-hidden
                    className="size-4 shrink-0 text-kura-fg opacity-0 transition-opacity duration-(--kura-duration-fast) group-has-checked:opacity-100"
                  />
                </label>
              ))}
            </fieldset>
          </div>
          <div className="flex items-center gap-2 border-kura-border-subtle border-t p-3">
            <input
              readOnly
              aria-label="Share link"
              value={shared ? "kura.chat/s/q3-churn-7f2a" : "Link sharing is off"}
              disabled={!shared}
              onFocus={(e) => e.currentTarget.select()}
              className="h-7 min-w-0 flex-1 rounded-kura-sm bg-kura-surface-sunken px-2 font-kura-mono text-kura-fg-muted text-xs shadow-kura-xs outline-none focus-visible:shadow-kura-focus disabled:font-kura-sans disabled:text-kura-fg-subtle"
            />
            <Button
              size="sm"
              disabled={!shared}
              onClick={() => {
                setCopied(true);
                clearTimeout(timer.current);
                timer.current = setTimeout(() => setCopied(false), 1600);
              }}
              className="w-26"
            >
              {copied ? <Check /> : <Link />}
              {copied ? "Copied" : "Copy link"}
            </Button>
          </div>
        </PopoverContent>
      </Popover>
    </div>
  );
}
```

## Dependencies

- npm: `radix-ui`
- Kura registry items: `kura-theme`, `utils`
- Related: `tooltip`, `model-picker`, `slash-command-menu`

---

# Prompt Suggestions

> Starter prompts for empty chat states — chips, cards or a list that rise in with a short stagger and fill the composer when clicked.

- **Slug:** `prompt-suggestions` · **Category:** input · **Status:** beta
- **Import:** `import { PromptSuggestion, PromptSuggestions } from "@kura-ui/react/prompt-suggestions";`
- **Docs:** https://kuro.abstergo.fyi/components/prompt-suggestions
- **Registry item:** https://kuro.abstergo.fyi/r/prompt-suggestions.json
- **Tags:** suggestions, starters, empty-state, prompts, chips, onboarding, stagger

## Install

```bash
# shadcn registry (copies source into your project)
npx shadcn@latest add https://kuro.abstergo.fyi/r/prompt-suggestions.json
# Kura CLI (same, plus dependency resolution and --json output)
npx @kura-ui/cli add prompt-suggestions
# npm package
npm install @kura-ui/react
```

## When to use

- The empty state of a chat or agent: show 3–6 example prompts the user can start from.
- Follow-up suggestions under an answer (“Make it shorter”, “Add sources”) using the chips variant.
- Onboarding that teaches what the assistant can do, with icons and one-line descriptions.

## When not to use

- Commands typed inline in the prompt — use slash-command-menu.
- Global actions and navigation — use command-palette.
- More than ~8 items or anything that needs search — use command-palette or a list.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `suggestions` | `readonly PromptSuggestion[]` | — | yes | Items: { id?, title, description?, icon?, prompt? }. `prompt` defaults to title + description. |
| `onSelect` | `(prompt: string, suggestion: PromptSuggestion) => void` | — | no | Called with the prompt text on click — typically sets the composer value. |
| `variant` | `"chips" \| "cards" \| "list"` | `"cards"` | no | chips = wrapping pills (titles only), cards = two-column tiles with icon and description, list = hairline-separated rows. |
| `stagger` | `number` | `0.04` | no | Seconds between items entering (30–50ms reads best). Capped after 8 items. |
| `label` | `string` | `"Suggestions"` | no | Accessible name of the list. |
| `disabled` | `boolean` | `false` | no | Disable every suggestion. |

Native attributes of the root element, `className` and `ref` are passed through.

## Anatomy

- **PromptSuggestions** (`data-slot="prompt-suggestions"`) — <ul> root; data-variant = chips | cards | list.
- **PromptSuggestionsItem** (`data-slot="prompt-suggestions-item"`) — Each suggestion is a native <button>; an arrow fades in on hover/focus (cards, list).
- **PromptSuggestionsIcon** (`data-slot="prompt-suggestions-icon"`) — Optional icon; a 28px tile in cards.

## Accessibility

- A labelled <ul> of native buttons; each button's name is its title (plus description).
- Icons and the hover arrow are aria-hidden.
- After filling a composer, move focus to its textarea so the user can edit and send (see the composition example).
- Reduced motion: Items fade in together-ish without rising or blurring; hover arrows and press scales do not move.

| Keys | Action |
| --- | --- |
| Tab / Shift+Tab | Move between suggestions |
| Enter / Space | Select a suggestion |

## Notes for agents

- Give items stable `id`s; changing the array with new ids animates the swap (old items fade out, new ones stagger in).
- Keep titles under ~6 words; put detail in `description` (cards/list only — chips show the title).
- To fill a Composer: control its `value`, call setValue(prompt) in onSelect, then focus the ComposerInput ref.
- Hide the suggestions once the conversation has messages; they are an empty-state affordance.

## Examples

### Chips (minimal)

```tsx
"use client";

import { PromptSuggestions } from "@kura-ui/react/prompt-suggestions";

export function PromptSuggestionsMinimal() {
  return (
    <PromptSuggestions
      variant="chips"
      suggestions={[
        { title: "Summarize a PDF" },
        { title: "Write a SQL query" },
        { title: "Plan a sprint" },
        { title: "Explain a regex" },
      ]}
      onSelect={(prompt) => console.log(prompt)}
    />
  );
}
```

### Cards with icons and refresh (full)

Swap the set to see items leave and stagger back in.

```tsx
"use client";

import { BookOpen, Bug, Calendar, ChartLine, Mail, Plane, RefreshCw, Scale, Telescope } from "lucide-react";
import * as React from "react";
import { Button } from "@kura-ui/react/button";
import { type PromptSuggestion, PromptSuggestions } from "@kura-ui/react/prompt-suggestions";

const sets: PromptSuggestion[][] = [
  [
    {
      id: "trip",
      title: "Plan a trip",
      description: "Four slow days in Kyoto in early April",
      icon: <Plane />,
    },
    {
      id: "metrics",
      title: "Analyze metrics",
      description: "Why did weekly actives dip after the release?",
      icon: <ChartLine />,
    },
    {
      id: "email",
      title: "Draft an email",
      description: "Decline a meeting without closing the door",
      icon: <Mail />,
    },
    {
      id: "bug",
      title: "Debug a crash",
      description: "TypeError: cannot read properties of undefined",
      icon: <Bug />,
    },
  ],
  [
    {
      id: "learn",
      title: "Teach me",
      description: "How transformers attend, with a tiny example",
      icon: <BookOpen />,
    },
    {
      id: "compare",
      title: "Compare options",
      description: "Postgres vs. SQLite for a local-first app",
      icon: <Scale />,
    },
    {
      id: "research",
      title: "Research",
      description: "What changed in the EU AI Act this year",
      icon: <Telescope />,
    },
    {
      id: "week",
      title: "Plan my week",
      description: "Fit deep work around six meetings",
      icon: <Calendar />,
    },
  ],
];

export function PromptSuggestionsFull() {
  const [set, setSet] = React.useState(0);
  const [picked, setPicked] = React.useState<string | null>(null);
  return (
    <div className="flex w-full max-w-xl flex-col gap-3">
      <PromptSuggestions
        variant="cards"
        label="Try one of these"
        stagger={0.05}
        suggestions={sets[set] ?? []}
        onSelect={(prompt) => setPicked(prompt)}
      />
      <div className="flex items-center justify-between gap-3 px-1">
        <p className="min-w-0 truncate text-kura-fg-subtle text-xs" aria-live="polite">
          {picked ? `Prompt: ${picked}` : "Pick a card"}
        </p>
        <Button variant="ghost" size="xs" onClick={() => setSet((s) => (s + 1) % sets.length)}>
          <RefreshCw />
          More ideas
        </Button>
      </div>
    </div>
  );
}
```

### Empty chat filling a composer (composition)

Selecting a row fills the composer and focuses it for editing.

```tsx
"use client";

import { ChartLine, FlaskConical, Mail } from "lucide-react";
import * as React from "react";
import {
  Composer,
  ComposerActions,
  ComposerAttachButton,
  ComposerInput,
  ComposerSubmit,
  ComposerToolbar,
  ComposerTools,
} from "@kura-ui/react/composer";
import { type PromptSuggestion, PromptSuggestions } from "@kura-ui/react/prompt-suggestions";

const starters: PromptSuggestion[] = [
  { title: "Summarize this week's customer feedback", icon: <ChartLine /> },
  { title: "Write tests for the billing service", icon: <FlaskConical /> },
  { title: "Draft a launch announcement", icon: <Mail /> },
];

export function PromptSuggestionsEmptyChat() {
  const [value, setValue] = React.useState("");
  const input = React.useRef<HTMLTextAreaElement>(null);
  return (
    <div className="flex w-full max-w-xl flex-col gap-5">
      <p className="text-balance text-center font-medium text-2xl text-kura-fg tracking-tight">
        What should we work on?
      </p>
      <Composer value={value} onValueChange={setValue} onSubmit={() => {}}>
        <ComposerInput ref={input} placeholder="Ask anything…" />
        <ComposerToolbar>
          <ComposerTools>
            <ComposerAttachButton />
          </ComposerTools>
          <ComposerActions>
            <ComposerSubmit />
          </ComposerActions>
        </ComposerToolbar>
      </Composer>
      <PromptSuggestions
        variant="list"
        suggestions={starters}
        onSelect={(prompt) => {
          setValue(prompt);
          input.current?.focus();
        }}
      />
    </div>
  );
}
```

## Dependencies

- npm: `lucide-react`, `motion`
- Kura registry items: `kura-theme`, `kura-motion`, `use-reduced-motion`, `utils`
- Related: `composer`, `slash-command-menu`, `command-palette`

---

# Reasoning

> Collapsible thinking trace: a shimmering “Thinking… 12s” label while active that settles into “Thought for 14s”, revealing muted reasoning text.

- **Slug:** `reasoning` · **Category:** agent · **Status:** beta
- **Import:** `import { Reasoning } from "@kura-ui/react/reasoning";`
- **Docs:** https://kuro.abstergo.fyi/components/reasoning
- **Registry item:** https://kuro.abstergo.fyi/r/reasoning.json
- **Tags:** reasoning, thinking, chain-of-thought, collapsible, trace, llm, timer

## Install

```bash
# shadcn registry (copies source into your project)
npx shadcn@latest add https://kuro.abstergo.fyi/r/reasoning.json
# Kura CLI (same, plus dependency resolution and --json output)
npx @kura-ui/cli add reasoning
# npm package
npm install @kura-ui/react
```

## When to use

- Show a reasoning model's chain of thought / thinking blocks (Claude extended thinking, o-series reasoning summaries) above the answer.
- Indicate that the model is thinking, with elapsed time, before the first answer token arrives.
- Keep a finished trace available but out of the way (collapsed to one line).

## When not to use

- A bare “Thinking…” label with no trace to reveal — use shimmer-text (or thinking-indicator).
- A sequence of discrete agent steps with states — use agent-timeline.
- A single tool invocation with arguments and results — use tool-call.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `active` | `boolean` | `false` | no | The model is still thinking: the label shimmers and an elapsed timer ticks. Turning it false settles the label and (with autoCollapse) collapses the trace. |
| `duration` | `number` | — | no | Seconds spent thinking, if you know it (e.g. stored with the message). Otherwise measured while `active`. |
| `open` | `boolean` | — | no | Expanded (controlled). |
| `defaultOpen` | `boolean` | — | no | Initial expanded state when uncontrolled. Defaults to `active`: open while thinking, closed for finished traces. |
| `onOpenChange` | `(open: boolean) => void` | — | no | Called when the trace is expanded/collapsed (by the reader or by auto-collapse). |
| `autoCollapse` | `boolean` | `true` | no | Collapse when `active` turns false — skipped if the reader toggled it while it was active. |
| `formatLabel` | `(state: { active: boolean; seconds: number }) => React.ReactNode` | — | no | Custom label (i18n, “Planning…”). Default “Thinking… 12s” / “Thought for 14s” / “Thought for a moment”. |

Native attributes of the root element, `className` and `ref` are passed through.

## Anatomy

- **Reasoning** (`data-slot="reasoning"`) — Root. `data-status="active" | "done"`, `data-state="open" | "closed"`.
- **Trigger** (`data-slot="reasoning-trigger"`) — Button with the label and a chevron that rotates 90° when open (aria-expanded, aria-controls).
- **Label** (`data-slot="reasoning-label"`) — ShimmerText; shimmers while active, muted when done. Seconds are tabular.
- **Content** (`data-slot="reasoning-content"`) — Muted, pre-wrapped trace behind a left hairline. Animates grid-template-rows 0fr↔1fr (interruptible) and is inert when closed.

## Accessibility

- The trigger is a real button with aria-expanded/aria-controls.
- A visually hidden status region says “Thinking” and then “Thought for 14s” — the ticking seconds are never announced.
- When collapsed, the trace is `inert`: out of the tab order and the accessibility tree.
- Reduced motion: The shimmer becomes static muted text, the chevron snaps, and the trace only fades (no height travel or blur).

| Keys | Action |
| --- | --- |
| Enter / Space | Expand or collapse the trace |

## Notes for agents

- Keep the component mounted from the first thinking token to the end; flip `active` instead of swapping components, so the timer and collapse work.
- Persist the measured duration with the message and pass it as `duration` when re-rendering history.
- Put a StreamingText (caret={false}) inside for a live trace; plain text or markdown for a stored one.

## Examples

### Finished trace (minimal)

A collapsed “Thought for 14s” trace.

```tsx
import { Reasoning } from "@kura-ui/react/reasoning";

const TRACE =
  "The user wants the like button to feel instant. The lag comes from waiting on the server round-trip before re-rendering.\n\nOptions: optimistic local state with manual rollback, or useOptimistic inside a transition. useOptimistic handles the rollback automatically if the action throws, and keeps the UI consistent with concurrent updates.\n\nI should recommend useOptimistic and show the minimal pattern, then mention the error case.";

export function ReasoningMinimal() {
  return (
    <Reasoning duration={14} className="w-full max-w-lg">
      {TRACE}
    </Reasoning>
  );
}
```

### Live thinking that auto-collapses (full)

Streams the trace with StreamingText while active (controlled open), then collapses to “Thought for Ns”.

```tsx
"use client";

import { RotateCcw } from "lucide-react";
import * as React from "react";
import { Button } from "@kura-ui/react/button";
import { StreamingText } from "@kura-ui/react/streaming-text";
import { Reasoning } from "@kura-ui/react/reasoning";

const TRACE =
  "The user wants the like button to feel instant. The lag comes from waiting on the server round-trip before re-rendering.\n\nOptions: optimistic local state with manual rollback, or useOptimistic inside a transition. useOptimistic handles the rollback automatically if the action throws, and keeps the UI consistent with concurrent updates.\n\nI should recommend useOptimistic and show the minimal pattern, then mention the error case.";

async function* thoughts(text: string): AsyncGenerator<string> {
  const words = text.split(/(?<=\s)/);
  for (let i = 0; i < words.length; i += 2) {
    yield words.slice(i, i + 2).join("");
    await new Promise((r) => setTimeout(r, 70 + Math.random() * 60));
  }
}

export function ReasoningFull() {
  const [run, setRun] = React.useState(0);
  const [active, setActive] = React.useState(true);
  const [open, setOpen] = React.useState(true);
  const [stream, setStream] = React.useState(() => thoughts(TRACE));

  const replay = () => {
    setRun((r) => r + 1);
    setStream(thoughts(TRACE));
    setActive(true);
    setOpen(true);
  };

  return (
    <div className="flex w-full max-w-lg flex-col items-start gap-4">
      <Reasoning
        key={run}
        active={active}
        open={open}
        onOpenChange={setOpen}
        autoCollapse
        className="w-full"
      >
        <StreamingText stream={stream} caret={false} onComplete={() => setActive(false)} />
      </Reasoning>
      <Button variant="secondary" size="sm" onClick={replay}>
        <RotateCcw /> Think again
      </Button>
    </div>
  );
}
```

### Above an assistant answer (composition)

Inside a Message, with a custom label.

```tsx
import * as React from "react";
import { Message, MessageAvatar } from "@kura-ui/react/message";
import { Reasoning } from "@kura-ui/react/reasoning";

const TRACE =
  "The user wants the like button to feel instant. The lag comes from waiting on the server round-trip before re-rendering.\n\nOptions: optimistic local state with manual rollback, or useOptimistic inside a transition. useOptimistic handles the rollback automatically if the action throws, and keeps the UI consistent with concurrent updates.\n\nI should recommend useOptimistic and show the minimal pattern, then mention the error case.";

export function ReasoningInMessage() {
  return (
    <Message
      from="assistant"
      name="Kura"
      avatar={<MessageAvatar name="Kura" />}
      className="max-w-xl"
    >
      <Reasoning
        duration={83}
        formatLabel={({ active, seconds }) =>
          active ? "Planning…" : `Planned for ${Math.round(seconds / 60)} min`
        }
      >
        {TRACE}
      </Reasoning>
      <p>
        Use <code>useOptimistic</code>: render the new count immediately, then let React reconcile
        when the server action resolves. If it throws, the optimistic value is dropped for you.
      </p>
    </Message>
  );
}
```

## Dependencies

- npm: `lucide-react`
- Kura registry items: `kura-theme`, `shimmer-text`, `use-controllable-state`, `utils`
- Related: `shimmer-text`, `thinking-indicator`, `message`, `streaming-text`, `agent-timeline`

---

# Shader Canvas

> Minimal WebGL2 fragment-shader runner with time/resolution/pointer uniforms, DPR capping, offscreen pausing, reduced-motion still frame and CSS fallback.

- **Slug:** `shader-canvas` · **Category:** effects · **Status:** beta
- **Import:** `import { ShaderCanvas, UniformInput, UniformValue } from "@kura-ui/react/shader-canvas";`
- **Docs:** https://kuro.abstergo.fyi/components/shader-canvas
- **Registry item:** https://kuro.abstergo.fyi/r/shader-canvas.json
- **Tags:** webgl, shader, glsl, gpu, background, gradient, effect, canvas

## Install

```bash
# shadcn registry (copies source into your project)
npx shadcn@latest add https://kuro.abstergo.fyi/r/shader-canvas.json
# Kura CLI (same, plus dependency resolution and --json output)
npx @kura-ui/cli add shader-canvas
# npm package
npm install @kura-ui/react
```

## When to use

- Building any GPU visual: mesh gradients, auroras, grain, glows, orbs, generative backgrounds.
- A custom decorative shader behind a hero, card or voice surface.

## When not to use

- A ready-made effect exists — use mesh-gradient, agent-orb, grain or border-beam.
- Static gradients — plain CSS is cheaper.
- Anything that conveys information — it is aria-hidden and may fall back to a static gradient.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `fragmentShader` | `string` | — | yes | GLSL ES 3.00 source. Without a #version line, a header declaring u_time, u_resolution, u_pointer and `out vec4 fragColor` is prepended. |
| `uniforms` | `Record<string, UniformInput>` | — | no | Custom uniforms: number→float, [x,y]→vec2, [x,y,z]→vec3, [x,y,z,w]→vec4, or a function of time evaluated every frame. Declare them in the shader. |
| `paused` | `boolean` | `false` | no | Freeze time on the current frame. |
| `speed` | `number` | `1` | no | Time multiplier. |
| `maxDpr` | `number` | `2` | no | Device-pixel-ratio cap. |
| `pauseWhenOffscreen` | `boolean` | `true` | no | Stop rendering when not visible. |
| `staticTime` | `number` | `1.5` | no | u_time used for the reduced-motion still frame. |
| `respectReducedMotion` | `boolean` | `true` | no | Render a single still frame when the user prefers reduced motion. |
| `fallback` | `React.ReactNode` | — | no | Shown when WebGL2 is unavailable or the shader fails. Default: a soft token gradient. |
| `onError` | `(message: string) => void` | — | no | Compile/link error callback. |

Native attributes of the root element, `className` and `ref` are passed through.

## Anatomy

- **ShaderCanvas** (`data-slot="shader-canvas"`) — Container div (size it with classes); `data-state` = running | paused | static | fallback.

## Accessibility

- Decorative: the container is aria-hidden. Never put meaning only in the shader.
- Respects prefers-reduced-motion with a single still frame.
- Reduced motion: Renders one frame at `staticTime` and stops the animation loop.

## Notes for agents

- Give the container an explicit size (e.g. `className="h-64 w-full rounded-kura-xl"`); the canvas fills it.
- Animate custom uniforms with function values `(t) => …` or by mutating an object you pass — not React state per frame.
- Colors in shaders cannot read CSS variables; pass them as vec3 uniforms (linear 0–1 RGB).

## Examples

### Gradient in a few lines (minimal)

```tsx
import { ShaderCanvas } from "@kura-ui/react/shader-canvas";

const gradient = /* glsl */ `
void main() {
  vec2 uv = gl_FragCoord.xy / u_resolution;
  vec3 a = vec3(0.07, 0.44, 0.38);
  vec3 b = vec3(0.93, 0.92, 0.88);
  float t = 0.5 + 0.5 * sin(u_time * 0.6 + uv.x * 3.0 + uv.y * 2.0);
  fragColor = vec4(mix(a, b, t), 1.0);
}`;

export function ShaderCanvasMinimal() {
  return (
    <ShaderCanvas fragmentShader={gradient} className="h-48 w-full max-w-md rounded-kura-xl" />
  );
}
```

### Silk with custom uniforms (full)

Custom color uniforms, speed control, pause and pointer response.

```tsx
"use client";

import * as React from "react";
import { Button } from "@kura-ui/react/button";
import { ShaderCanvas } from "@kura-ui/react/shader-canvas";

const silk = /* glsl */ `
uniform vec3 u_colorA;
uniform vec3 u_colorB;
uniform vec3 u_colorC;

float hash(vec2 p) { return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453); }
float noise(vec2 p) {
  vec2 i = floor(p), f = fract(p);
  vec2 u = f * f * (3.0 - 2.0 * f);
  return mix(mix(hash(i), hash(i + vec2(1, 0)), u.x), mix(hash(i + vec2(0, 1)), hash(i + vec2(1, 1)), u.x), u.y);
}
float fbm(vec2 p) {
  float v = 0.0, a = 0.5;
  for (int i = 0; i < 5; i++) { v += a * noise(p); p *= 2.02; a *= 0.5; }
  return v;
}

void main() {
  vec2 uv = gl_FragCoord.xy / u_resolution;
  vec2 p = uv * vec2(u_resolution.x / u_resolution.y, 1.0) * 2.2;
  float t = u_time * 0.12;
  vec2 q = vec2(fbm(p + t), fbm(p - t + 3.1));
  vec2 r = vec2(fbm(p + 2.0 * q + vec2(1.7, 9.2) + t), fbm(p + 2.0 * q + vec2(8.3, 2.8)));
  r += (u_pointer - 0.5) * 0.35;
  float f = fbm(p + 2.5 * r);
  vec3 col = mix(u_colorA, u_colorB, smoothstep(0.2, 0.8, f));
  col = mix(col, u_colorC, smoothstep(0.55, 1.0, length(q)));
  col += 0.04 * (hash(gl_FragCoord.xy + u_time) - 0.5); // grain
  fragColor = vec4(col, 1.0);
}`;

export function ShaderCanvasFull() {
  const [paused, setPaused] = React.useState(false);
  const [speed, setSpeed] = React.useState(1);
  return (
    <div className="flex w-full max-w-lg flex-col gap-3">
      <ShaderCanvas
        fragmentShader={silk}
        uniforms={{
          u_colorA: [0.05, 0.09, 0.08],
          u_colorB: [0.12, 0.55, 0.47],
          u_colorC: [0.92, 0.9, 0.84],
        }}
        paused={paused}
        speed={speed}
        maxDpr={1.5}
        staticTime={4}
        className="h-64 w-full rounded-kura-xl shadow-kura-md"
      />
      <div className="flex items-center gap-2">
        <Button size="sm" variant="secondary" onClick={() => setPaused((p) => !p)}>
          {paused ? "Play" : "Pause"}
        </Button>
        <Button size="sm" variant="ghost" onClick={() => setSpeed((s) => (s >= 4 ? 0.5 : s * 2))}>
          Speed ×{speed}
        </Button>
      </div>
    </div>
  );
}
```

### Feature card with a live band (composition)

A ShaderCanvas header behind a glass chip, with copy, stats and Buttons on a token surface.

```tsx
import { ArrowRight, Telescope } from "lucide-react";
import { Button } from "@kura-ui/react/button";
import { ShaderCanvas } from "@kura-ui/react/shader-canvas";

const ribbons = /* glsl */ `
uniform vec3 u_deep;
uniform vec3 u_jade;
uniform vec3 u_mist;

float hash(vec2 p) { return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453); }

void main() {
  vec2 uv = gl_FragCoord.xy / u_resolution;
  float aspect = u_resolution.x / u_resolution.y;
  float x = uv.x * aspect;
  float t = u_time * 0.2;

  // Deep base with a slow jade bloom that leans toward the pointer.
  vec2 bloom = vec2(0.5 + 0.25 * sin(t * 0.7), 0.35) * 0.6 + u_pointer * 0.4;
  float halo = smoothstep(0.9, 0.0, length((uv - bloom) * vec2(aspect * 0.6, 1.0)));
  vec3 col = mix(u_deep, u_jade * 0.7, halo * 0.75);

  // Three silk ribbons drifting across the band.
  float glow = 0.0;
  for (int i = 0; i < 3; i++) {
    float fi = float(i);
    float y = 0.5 + 0.2 * sin(x * (0.9 + fi * 0.3) + t * (1.0 + fi * 0.35) + fi * 2.1)
                  + 0.07 * sin(x * 2.6 - t * 1.6 + fi * 1.3);
    float d = abs(uv.y - y);
    glow += (0.012 + 0.006 * fi) / (d + 0.012) * (0.9 - fi * 0.2);
  }
  col = mix(col, u_jade, clamp(glow * 0.45, 0.0, 1.0));
  col = mix(col, u_mist, smoothstep(1.2, 3.0, glow));
  col += 0.025 * (hash(gl_FragCoord.xy + u_time) - 0.5); // grain
  fragColor = vec4(col, 1.0);
}`;

const silk = /* glsl */ `
uniform vec3 u_colorA;
uniform vec3 u_colorB;
uniform vec3 u_colorC;

float hash(vec2 p) { return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453); }
float noise(vec2 p) {
  vec2 i = floor(p), f = fract(p);
  vec2 u = f * f * (3.0 - 2.0 * f);
  return mix(mix(hash(i), hash(i + vec2(1, 0)), u.x), mix(hash(i + vec2(0, 1)), hash(i + vec2(1, 1)), u.x), u.y);
}
float fbm(vec2 p) {
  float v = 0.0, a = 0.5;
  for (int i = 0; i < 5; i++) { v += a * noise(p); p *= 2.02; a *= 0.5; }
  return v;
}

void main() {
  vec2 uv = gl_FragCoord.xy / u_resolution;
  vec2 p = uv * vec2(u_resolution.x / u_resolution.y, 1.0) * 2.2;
  float t = u_time * 0.12;
  vec2 q = vec2(fbm(p + t), fbm(p - t + 3.1));
  vec2 r = vec2(fbm(p + 2.0 * q + vec2(1.7, 9.2) + t), fbm(p + 2.0 * q + vec2(8.3, 2.8)));
  r += (u_pointer - 0.5) * 0.35;
  float f = fbm(p + 2.5 * r);
  vec3 col = mix(u_colorA, u_colorB, smoothstep(0.2, 0.8, f));
  col = mix(col, u_colorC, smoothstep(0.55, 1.0, length(q)));
  col += 0.04 * (hash(gl_FragCoord.xy + u_time) - 0.5); // grain
  fragColor = vec4(col, 1.0);
}`;

export function ShaderCanvasFeatureCard() {
  return (
    <article className="relative isolate flex w-full max-w-md flex-col overflow-hidden rounded-kura-2xl bg-kura-surface shadow-kura-md">
      <div className="relative h-44">
        <ShaderCanvas
          fragmentShader={ribbons}
          uniforms={{
            u_deep: [0.035, 0.09, 0.08],
            u_jade: [0.12, 0.6, 0.5],
            u_mist: [0.86, 0.95, 0.9],
          }}
          maxDpr={1.5}
          staticTime={6}
          className="absolute inset-0"
        />
        <span className="absolute top-3 left-3 inline-flex items-center gap-1.5 rounded-full bg-kura-overlay px-2.5 py-1 font-medium text-kura-fg text-xs shadow-kura-xs backdrop-blur-xl">
          <Telescope className="size-3.5" aria-hidden />
          Deep research
        </span>
      </div>
      <div className="flex flex-col gap-4 p-5">
        <div className="flex flex-col gap-1.5">
          <h3 className="font-medium text-kura-fg text-lg tracking-tight">
            Hand off the reading, keep the judgement
          </h3>
          <p className="text-kura-fg-muted text-sm leading-relaxed">
            Kura searches, reads and cross-checks dozens of sources, then brings back a cited brief
            you can question line by line.
          </p>
        </div>
        <dl className="flex gap-6 font-kura-mono text-xs tabular-nums">
          <div className="flex flex-col gap-0.5">
            <dt className="text-kura-fg-subtle">Typical run</dt>
            <dd className="text-kura-fg">4–6 min</dd>
          </div>
          <div className="flex flex-col gap-0.5">
            <dt className="text-kura-fg-subtle">Sources</dt>
            <dd className="text-kura-fg">30–60</dd>
          </div>
          <div className="flex flex-col gap-0.5">
            <dt className="text-kura-fg-subtle">Included</dt>
            <dd className="text-kura-fg">25 / month</dd>
          </div>
        </dl>
        <div className="flex items-center gap-2">
          <Button>
            Start a brief
            <ArrowRight />
          </Button>
          <Button variant="ghost">See an example</Button>
        </div>
      </div>
    </article>
  );
}
```

## Dependencies

- npm: none
- Kura registry items: `kura-theme`, `kura-merge-refs`, `use-reduced-motion`, `utils`
- Related: `mesh-gradient`, `agent-orb`, `grain`, `border-beam`

---

# Shimmer Text

> Animated gradient sweep across text — the canonical “Thinking…” / “Searching…” label for in-progress AI work.

- **Slug:** `shimmer-text` · **Category:** feedback · **Status:** beta
- **Import:** `import { ShimmerText } from "@kura-ui/react/shimmer-text";`
- **Docs:** https://kuro.abstergo.fyi/components/shimmer-text
- **Registry item:** https://kuro.abstergo.fyi/r/shimmer-text.json
- **Tags:** loading, thinking, status, text, animation, shimmer, skeleton, progress

## Install

```bash
# shadcn registry (copies source into your project)
npx shadcn@latest add https://kuro.abstergo.fyi/r/shimmer-text.json
# Kura CLI (same, plus dependency resolution and --json output)
npx @kura-ui/cli add shimmer-text
# npm package
npm install @kura-ui/react
```

## When to use

- Show that a model or agent is working: “Thinking…”, “Searching the web…”, “Reading 12 files…”.
- Label the current step of a running tool call or reasoning trace.
- A lightweight inline loading label where a spinner would be too mechanical.

## When not to use

- Long paragraphs or body text — the sweep hurts legibility beyond a short phrase.
- Determinate progress (uploads, token budgets) — use a progress bar or context-meter.
- Streaming the model's answer itself — use streaming-text.
- A standalone animated dot/orb indicator — use thinking-indicator or agent-orb.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `children` | `React.ReactNode` | — | yes | The text to shimmer. Plain text reads best; inline elements are allowed. |
| `active` | `boolean` | `true` | no | Animate the sweep. Set false when the work finishes to settle into muted text. |
| `duration` | `number` | `2` | no | Seconds per sweep. Keep between 1.5 (urgent) and 3 (calm). |
| `spread` | `number` | `30` | no | Width of the bright band as a % of the text width (clamped 5–80). |
| `as` | `"span" \| "p" \| "div" \| "strong" \| "em"` | `"span"` | no | Element to render. |

Native attributes of the root element, `className` and `ref` are passed through.

## Anatomy

- **ShimmerText** (`data-slot="shimmer-text"`) — A single inline element; `data-active` reflects the `active` prop.

## Accessibility

- The text stays real text: screen readers read it normally; the animation is purely visual.
- Not a live region. Wrap the label in an element with role="status" (or aria-live="polite") if the change of state should be announced.
- Colors come from fg/fg-subtle tokens so contrast holds in light and dark mode.
- Reduced motion: The sweep is removed; the text renders as static muted text.

## Notes for agents

- Server-component safe: no hooks, pure CSS animation. No "use client" needed to render it.
- Flip `active` to false instead of unmounting when work completes, so layout does not jump.
- Keep the label under ~6 words and end with an ellipsis (…) while active.

## Examples

### Thinking label (minimal)

The smallest correct usage.

```tsx
import { ShimmerText } from "@kura-ui/react/shimmer-text";

export function ShimmerTextMinimal() {
  return <ShimmerText>Thinking…</ShimmerText>;
}
```

### Tuned sweep (full)

Every prop: element, speed, band width, and toggling `active` when work completes.

```tsx
"use client";

import * as React from "react";
import { Button } from "@kura-ui/react/button";
import { ShimmerText } from "@kura-ui/react/shimmer-text";

export function ShimmerTextFull() {
  const [active, setActive] = React.useState(true);
  return (
    <div className="flex flex-col items-center gap-4">
      <ShimmerText as="p" active={active} duration={2.4} spread={24} className="text-lg">
        {active ? "Searching 24 sources…" : "Searched 24 sources"}
      </ShimmerText>
      <Button variant="secondary" size="sm" onClick={() => setActive((a) => !a)}>
        {active ? "Finish" : "Restart"}
      </Button>
    </div>
  );
}
```

### Agent step with status region (composition)

A tool-call style row announcing progress politely to screen readers.

```tsx
"use client";

import { Check } from "lucide-react";
import * as React from "react";
import { ShimmerText } from "@kura-ui/react/shimmer-text";

export function ShimmerTextInToolStep() {
  const [done, setDone] = React.useState(false);
  React.useEffect(() => {
    const id = setTimeout(() => setDone(true), 3200);
    return () => clearTimeout(id);
  }, []);
  return (
    <div className="flex w-72 items-center gap-2.5 rounded-kura-lg bg-kura-surface px-3 py-2.5 text-sm shadow-kura-sm">
      <span className="flex size-5 items-center justify-center rounded-full bg-kura-accent-subtle text-kura-accent-text">
        {done ? (
          <Check className="size-3" />
        ) : (
          <span className="size-1.5 animate-kura-pulse rounded-full bg-current" />
        )}
      </span>
      <span role="status" aria-live="polite">
        <ShimmerText active={!done}>
          {done ? "Read package.json" : "Reading package.json…"}
        </ShimmerText>
      </span>
    </div>
  );
}
```

## Dependencies

- npm: none
- Kura registry items: `kura-theme`, `utils`
- Related: `thinking-indicator`, `reasoning`, `tool-call`, `streaming-text`

---

# Slash Command Menu

> Inline “/” command menu anchored to the caret of a textarea, with filtering, groups, icons, descriptions and keyboard navigation.

- **Slug:** `slash-command-menu` · **Category:** input · **Status:** beta
- **Import:** `import { CaretRect, SlashCommand, SlashCommandMenu, SlashCommandSelectDetails } from "@kura-ui/react/slash-command-menu";`
- **Docs:** https://kuro.abstergo.fyi/components/slash-command-menu
- **Registry item:** https://kuro.abstergo.fyi/r/slash-command-menu.json
- **Tags:** slash, commands, autocomplete, mention, caret, menu, composer, textarea

## Install

```bash
# shadcn registry (copies source into your project)
npx shadcn@latest add https://kuro.abstergo.fyi/r/slash-command-menu.json
# Kura CLI (same, plus dependency resolution and --json output)
npx @kura-ui/cli add slash-command-menu
# npm package
npm install @kura-ui/react
```

## When to use

- Let users insert prompt templates or run actions by typing “/” in a composer (/summarize, /debug, /clear).
- Any textarea or input that needs caret-anchored suggestions triggered by a character (use `trigger` for “@” mentions or “#” tags).

## When not to use

- A global ⌘K launcher for navigation and actions — use command-palette.
- Choosing a model from a toolbar — use model-picker.
- Static clickable starters in an empty chat — use prompt-suggestions.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `textareaRef` | `React.RefObject<HTMLTextAreaElement \| HTMLInputElement \| null>` | — | yes | Ref to the field to watch, e.g. the `ref` you pass to ComposerInput. The menu never takes focus from it. |
| `commands` | `readonly SlashCommand[]` | — | yes | Commands: { id, label, description?, icon?, group?, keywords?, shortcut?, insert?, disabled? }. |
| `onSelect` | `(command: SlashCommand, details: SlashCommandSelectDetails) => void` | — | no | Called after the typed “/query” has been replaced by `command.insert` (or removed). details.query is what was typed. |
| `onOpenChange` | `(open: boolean) => void` | — | no | Called when the menu opens or closes. |
| `trigger` | `string` | `"/"` | no | Trigger character. Only fires at the start of a line or after whitespace. |
| `side` | `"auto" \| "top" \| "bottom"` | `"auto"` | no | auto opens below the caret and flips above when there is no room. |
| `emptyMessage` | `string \| null` | `"No commands"` | no | Shown when nothing matches; null closes the menu instead. |
| `disabled` | `boolean` | `false` | no | Stop watching the field without unmounting. |

Native attributes of the root element, `className` and `ref` are passed through.

## Anatomy

- **SlashCommandMenu** (`data-slot="slash-command-menu"`) — Floating panel portalled to <body>, position: fixed at the trigger character. data-side = top | bottom; scales from the caret corner.
- **SlashCommandMenuGroup** (`data-slot="slash-command-menu-group"`) — role=group per `group`, labelled by its heading.
- **SlashCommandMenuItem** (`data-slot="slash-command-menu-item"`) — role=option row: icon tile, label (matched text emphasised), description, shortcut. data-active, data-disabled.
- **SlashCommandMenuFooter** (`data-slot="slash-command-menu-footer"`) — Key hints: ↑↓ navigate, ↵ insert, Esc dismiss.

## Accessibility

- Role: `listbox`
- Focus never leaves the textarea. While open, the textarea gets aria-controls, aria-autocomplete=list and aria-activedescendant pointing at the highlighted option, so screen readers read the option as you arrow.
- A polite status announces the number of matching commands.
- Pointer selection uses mousedown preventDefault so the textarea keeps focus and its caret.
- Insertion uses the browser's insertText command where available, so ⌘Z undoes a command like normal typing.
- Reduced motion: The menu fades in without the scale and 2px travel.

| Keys | Action |
| --- | --- |
| / | Open (at line start or after a space) |
| ArrowDown / ArrowUp | Move the highlight (wraps, skips disabled) |
| Enter / Tab | Insert the highlighted command |
| Escape | Dismiss for this “/” (typing on does not reopen it) |
| Space / Backspace past / | Closes the menu |

## Notes for agents

- Render the menu next to the field (anywhere in the tree); it portals itself to <body> and positions at the caret.
- It works with controlled fields: the replacement dispatches a native input event, so React onChange / Composer onValueChange fire.
- Use `insert` for prompt templates; omit it for actions and handle them in onSelect (e.g. id === "clear").
- Its keydown listener runs before React handlers and stops Enter/Tab/arrows while open, so Composer will not send mid-selection.
- getCaretRect(field, offset) is exported if you need caret coordinates for something else.

## Examples

### On a plain textarea (minimal)

```tsx
import {
  AlignLeft,
  Bug,
  Code,
  Eraser,
  Globe,
  Languages,
  ListTodo,
  MessageSquarePlus,
  PenLine,
  TestTube,
} from "lucide-react";
import * as React from "react";
import { type SlashCommand, SlashCommandMenu } from "@kura-ui/react/slash-command-menu";

const basic: SlashCommand[] = [
  { id: "summarize", label: "Summarize", insert: "Summarize the following:\n" },
  { id: "translate", label: "Translate", insert: "Translate into " },
  { id: "explain", label: "Explain", insert: "Explain like I'm new to this: " },
];

const commands: SlashCommand[] = [
  {
    id: "summarize",
    label: "Summarize",
    description: "Condense text into key points",
    icon: <AlignLeft />,
    group: "Write",
    keywords: ["tldr", "shorten"],
    insert: "Summarize the following in 5 bullet points:\n",
  },
  {
    id: "rewrite",
    label: "Rewrite",
    description: "Change tone, length or clarity",
    icon: <PenLine />,
    group: "Write",
    insert: "Rewrite this to be clearer and more concise:\n",
  },
  {
    id: "translate",
    label: "Translate",
    description: "Into any language",
    icon: <Languages />,
    group: "Write",
    insert: "Translate into ",
  },
  {
    id: "explain",
    label: "Explain code",
    description: "Walk through what a snippet does",
    icon: <Code />,
    group: "Code",
    insert: "Explain this code step by step:\n```\n\n```",
  },
  {
    id: "debug",
    label: "Debug",
    description: "Find the cause of an error",
    icon: <Bug />,
    group: "Code",
    keywords: ["fix", "error", "stack trace"],
    insert: "Here is an error. Find the root cause:\n",
  },
  {
    id: "tests",
    label: "Write tests",
    description: "Unit tests for the selected function",
    icon: <TestTube />,
    group: "Code",
    insert: "Write Vitest unit tests for:\n",
  },
  {
    id: "plan",
    label: "Plan",
    description: "Break a goal into steps first",
    icon: <ListTodo />,
    group: "Agent",
    insert: "Before doing anything, write a step-by-step plan for: ",
  },
  {
    id: "search",
    label: "Search the web",
    description: "Ground the answer in fresh sources",
    icon: <Globe />,
    group: "Agent",
    disabled: true,
  },
  {
    id: "new",
    label: "New chat",
    icon: <MessageSquarePlus />,
    group: "Session",
    shortcut: ["mod", "shift", "o"],
  },
  { id: "clear", label: "Clear input", icon: <Eraser />, group: "Session" },
];

export function SlashCommandMenuMinimal() {
  const ref = React.useRef<HTMLTextAreaElement>(null);
  return (
    <div className="w-full max-w-md">
      <textarea
        ref={ref}
        aria-label="Prompt"
        placeholder="Type / for commands"
        rows={3}
        className="w-full resize-none rounded-kura-lg bg-kura-surface px-3 py-2.5 text-sm shadow-kura-sm outline-none placeholder:text-kura-fg-subtle focus-visible:shadow-kura-focus"
      />
      <SlashCommandMenu textareaRef={ref} commands={basic} />
    </div>
  );
}
```

### Groups, icons, shortcuts and actions (full)

Ten commands in four groups, a disabled command, keywords (/tldr finds Summarize) and an action that clears the input.

```tsx
"use client";

import {
  AlignLeft,
  Bug,
  Code,
  Eraser,
  Globe,
  Languages,
  ListTodo,
  MessageSquarePlus,
  PenLine,
  TestTube,
} from "lucide-react";
import * as React from "react";
import { type SlashCommand, SlashCommandMenu } from "@kura-ui/react/slash-command-menu";

const commands: SlashCommand[] = [
  {
    id: "summarize",
    label: "Summarize",
    description: "Condense text into key points",
    icon: <AlignLeft />,
    group: "Write",
    keywords: ["tldr", "shorten"],
    insert: "Summarize the following in 5 bullet points:\n",
  },
  {
    id: "rewrite",
    label: "Rewrite",
    description: "Change tone, length or clarity",
    icon: <PenLine />,
    group: "Write",
    insert: "Rewrite this to be clearer and more concise:\n",
  },
  {
    id: "translate",
    label: "Translate",
    description: "Into any language",
    icon: <Languages />,
    group: "Write",
    insert: "Translate into ",
  },
  {
    id: "explain",
    label: "Explain code",
    description: "Walk through what a snippet does",
    icon: <Code />,
    group: "Code",
    insert: "Explain this code step by step:\n```\n\n```",
  },
  {
    id: "debug",
    label: "Debug",
    description: "Find the cause of an error",
    icon: <Bug />,
    group: "Code",
    keywords: ["fix", "error", "stack trace"],
    insert: "Here is an error. Find the root cause:\n",
  },
  {
    id: "tests",
    label: "Write tests",
    description: "Unit tests for the selected function",
    icon: <TestTube />,
    group: "Code",
    insert: "Write Vitest unit tests for:\n",
  },
  {
    id: "plan",
    label: "Plan",
    description: "Break a goal into steps first",
    icon: <ListTodo />,
    group: "Agent",
    insert: "Before doing anything, write a step-by-step plan for: ",
  },
  {
    id: "search",
    label: "Search the web",
    description: "Ground the answer in fresh sources",
    icon: <Globe />,
    group: "Agent",
    disabled: true,
  },
  {
    id: "new",
    label: "New chat",
    icon: <MessageSquarePlus />,
    group: "Session",
    shortcut: ["mod", "shift", "o"],
  },
  { id: "clear", label: "Clear input", icon: <Eraser />, group: "Session" },
];

export function SlashCommandMenuFull() {
  const ref = React.useRef<HTMLTextAreaElement>(null);
  const [value, setValue] = React.useState("");
  const [log, setLog] = React.useState("Type / at the start of a line");
  return (
    <div className="flex w-full max-w-md flex-col gap-2">
      <textarea
        ref={ref}
        aria-label="Prompt"
        value={value}
        onChange={(e) => setValue(e.currentTarget.value)}
        placeholder="Write a message… try /sum or /debug"
        rows={4}
        className="w-full resize-none rounded-kura-lg bg-kura-surface px-3 py-2.5 text-sm leading-6 shadow-kura-sm outline-none placeholder:text-kura-fg-subtle focus-visible:shadow-kura-focus"
      />
      <SlashCommandMenu
        textareaRef={ref}
        commands={commands}
        trigger="/"
        side="auto"
        emptyMessage="No matching command"
        onOpenChange={(open) => setLog(open ? "Menu open" : "Menu closed")}
        onSelect={(command, { query }) => {
          if (command.id === "clear") setValue("");
          setLog(`Ran /${command.label}${query ? ` (typed “/${query}”)` : ""}`);
        }}
      />
      <p className="px-1 text-kura-fg-subtle text-xs" aria-live="polite">
        {log}
      </p>
    </div>
  );
}
```

### Inside a composer (composition)

Pass the ComposerInput ref; Enter inserts the command instead of sending while the menu is open.

```tsx
"use client";

import {
  AlignLeft,
  Bug,
  Code,
  Eraser,
  Globe,
  Languages,
  ListTodo,
  MessageSquarePlus,
  PenLine,
  TestTube,
} from "lucide-react";
import * as React from "react";
import {
  Composer,
  ComposerActions,
  ComposerAttachButton,
  ComposerHint,
  ComposerInput,
  ComposerSubmit,
  ComposerToolbar,
  ComposerTools,
} from "@kura-ui/react/composer";
import { KbdShortcut } from "@kura-ui/react/kbd-shortcut";
import { type SlashCommand, SlashCommandMenu } from "@kura-ui/react/slash-command-menu";

const commands: SlashCommand[] = [
  {
    id: "summarize",
    label: "Summarize",
    description: "Condense text into key points",
    icon: <AlignLeft />,
    group: "Write",
    keywords: ["tldr", "shorten"],
    insert: "Summarize the following in 5 bullet points:\n",
  },
  {
    id: "rewrite",
    label: "Rewrite",
    description: "Change tone, length or clarity",
    icon: <PenLine />,
    group: "Write",
    insert: "Rewrite this to be clearer and more concise:\n",
  },
  {
    id: "translate",
    label: "Translate",
    description: "Into any language",
    icon: <Languages />,
    group: "Write",
    insert: "Translate into ",
  },
  {
    id: "explain",
    label: "Explain code",
    description: "Walk through what a snippet does",
    icon: <Code />,
    group: "Code",
    insert: "Explain this code step by step:\n```\n\n```",
  },
  {
    id: "debug",
    label: "Debug",
    description: "Find the cause of an error",
    icon: <Bug />,
    group: "Code",
    keywords: ["fix", "error", "stack trace"],
    insert: "Here is an error. Find the root cause:\n",
  },
  {
    id: "tests",
    label: "Write tests",
    description: "Unit tests for the selected function",
    icon: <TestTube />,
    group: "Code",
    insert: "Write Vitest unit tests for:\n",
  },
  {
    id: "plan",
    label: "Plan",
    description: "Break a goal into steps first",
    icon: <ListTodo />,
    group: "Agent",
    insert: "Before doing anything, write a step-by-step plan for: ",
  },
  {
    id: "search",
    label: "Search the web",
    description: "Ground the answer in fresh sources",
    icon: <Globe />,
    group: "Agent",
    disabled: true,
  },
  {
    id: "new",
    label: "New chat",
    icon: <MessageSquarePlus />,
    group: "Session",
    shortcut: ["mod", "shift", "o"],
  },
  { id: "clear", label: "Clear input", icon: <Eraser />, group: "Session" },
];

export function SlashCommandMenuInComposer() {
  const ref = React.useRef<HTMLTextAreaElement>(null);
  const [value, setValue] = React.useState("");
  return (
    <div className="flex w-full max-w-xl flex-col gap-2">
      <Composer value={value} onValueChange={setValue} onSubmit={() => {}}>
        <ComposerInput ref={ref} placeholder="Ask anything, or type / for commands" />
        <ComposerToolbar>
          <ComposerTools>
            <ComposerAttachButton />
          </ComposerTools>
          <ComposerActions>
            <ComposerHint />
            <ComposerSubmit />
          </ComposerActions>
        </ComposerToolbar>
      </Composer>
      <SlashCommandMenu
        textareaRef={ref}
        commands={commands}
        side="top"
        onSelect={(command) => {
          if (command.id === "clear") setValue("");
        }}
      />
      <div className="flex gap-3 px-1">
        <KbdShortcut keys={["/"]} label="Commands" variant="ghost" />
        <KbdShortcut keys={["enter"]} label="Send" variant="ghost" />
      </div>
    </div>
  );
}
```

## Dependencies

- npm: none
- Kura registry items: `kura-theme`, `kbd`, `kura-keys`, `utils`
- Related: `composer`, `command-palette`, `prompt-suggestions`

---

# Spinner

> Eight-segment radial spinner for indeterminate loading that inherits the current text color.

- **Slug:** `spinner` · **Category:** primitives · **Status:** stable
- **Import:** `import { Spinner } from "@kura-ui/react/spinner";`
- **Docs:** https://kuro.abstergo.fyi/components/spinner
- **Registry item:** https://kuro.abstergo.fyi/r/spinner.json
- **Tags:** loading, spinner, busy, progress, indeterminate

## Install

```bash
# shadcn registry (copies source into your project)
npx shadcn@latest add https://kuro.abstergo.fyi/r/spinner.json
# Kura CLI (same, plus dependency resolution and --json output)
npx @kura-ui/cli add spinner
# npm package
npm install @kura-ui/react
```

## When to use

- Indeterminate waits on a control: a loading button, a pending row, a fetching list.
- Small inline busy indicators next to text.

## When not to use

- AI ‘thinking’ states — use shimmer-text or thinking-indicator; they read as the model working, not the network.
- Known progress — use a progress bar or context-meter.
- Inside a Button — pass `loading` to button instead.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | no | 12px, 16px or 20px. |
| `label` | `string \| null` | `"Loading"` | no | Accessible label (role=status). Pass null when a parent already announces loading. |

Native attributes of the root element, `className` and `ref` are passed through.

## Accessibility

- Role: `status`
- With a label it renders role="status" containing visually hidden label text; with label={null} it is aria-hidden.
- Reduced motion: Rotation is replaced by a slow opacity pulse.

## Notes for agents

- Color it with a text-* class on the spinner or a parent; it uses currentColor.

## Examples

### Default (minimal)

```tsx
import { Spinner } from "@kura-ui/react/spinner";

export function SpinnerMinimal() {
  return <Spinner />;
}
```

### Sizes and colors (full)

```tsx
import { Spinner } from "@kura-ui/react/spinner";

export function SpinnerFull() {
  return (
    <div className="flex items-center gap-6 text-kura-fg-muted">
      <Spinner size="sm" label="Loading small" />
      <Spinner size="md" label="Loading medium" />
      <Spinner size="lg" label="Loading large" className="text-kura-accent" />
      <span className="inline-flex items-center gap-2 text-sm">
        <Spinner size="sm" label={null} /> Fetching models…
      </span>
    </div>
  );
}
```

### Syncing knowledge sources (composition)

Per-row spinners for indexing, a loading Sync now Button and a Reconnect action for a failed source.

```tsx
"use client";

import { Check, FileText, FolderGit2, HardDrive, ListTodo, TriangleAlert } from "lucide-react";
import * as React from "react";
import { Button } from "@kura-ui/react/button";
import { Spinner } from "@kura-ui/react/spinner";

const initialSources: Array<{
  id: string;
  name: string;
  detail: string;
  icon: React.ReactNode;
  status: SourceStatus;
}> = [
  {
    id: "drive",
    name: "Product specs",
    detail: "Drive · 1,204 files",
    icon: <HardDrive />,
    status: "synced",
  },
  {
    id: "wiki",
    name: "Team wiki",
    detail: "Notion · 386 pages",
    icon: <FileText />,
    status: "syncing",
  },
  {
    id: "repo",
    name: "kura-ui/kura",
    detail: "GitHub · main",
    icon: <FolderGit2 />,
    status: "synced",
  },
  {
    id: "issues",
    name: "Roadmap issues",
    detail: "Linear · access expired",
    icon: <ListTodo />,
    status: "error",
  },
];

export function SpinnerSourcesList() {
  const [sources, setSources] = React.useState(initialSources);
  const [syncingAll, setSyncingAll] = React.useState(false);
  const syncing = sources.some((s) => s.status === "syncing");
  const timers = React.useRef<ReturnType<typeof setTimeout>[]>([]);
  React.useEffect(() => () => timers.current.forEach(clearTimeout), []);

  // Let the initial "Team wiki" sync finish so the demo settles.
  React.useEffect(() => {
    const id = setTimeout(
      () => setSources((all) => all.map((s) => (s.id === "wiki" ? { ...s, status: "synced" } : s))),
      3200,
    );
    return () => clearTimeout(id);
  }, []);

  const settle = (id: string, ms: number) =>
    timers.current.push(
      setTimeout(
        () => setSources((all) => all.map((s) => (s.id === id ? { ...s, status: "synced" } : s))),
        ms,
      ),
    );
  const syncOne = (id: string) => {
    setSources((all) => all.map((s) => (s.id === id ? { ...s, status: "syncing" } : s)));
    settle(id, 1800);
  };
  // Re-index healthy sources; one that needs reconnecting stays put until the user acts.
  const syncAll = () => {
    const healthy = sources.filter((s) => s.status !== "error");
    setSources((all) => all.map((s) => (s.status === "error" ? s : { ...s, status: "syncing" })));
    for (const [i, s] of healthy.entries()) settle(s.id, 900 + i * 650);
    setSyncingAll(true);
    timers.current.push(setTimeout(() => setSyncingAll(false), 900 + healthy.length * 650));
  };

  return (
    <section
      aria-labelledby="sources-title"
      className="flex w-full max-w-md flex-col rounded-kura-xl bg-kura-surface shadow-kura-sm"
    >
      <div className="flex items-center justify-between gap-3 px-4 pt-4 pb-2">
        <div className="flex flex-col gap-0.5">
          <h3 id="sources-title" className="font-medium text-kura-fg text-sm">
            Knowledge sources
          </h3>
          <p className="text-kura-fg-muted text-xs" aria-live="polite">
            {syncing ? "Syncing — answers may miss recent changes" : "Indexed 2 minutes ago"}
          </p>
        </div>
        <Button variant="secondary" size="sm" loading={syncingAll} onClick={syncAll}>
          Sync now
        </Button>
      </div>
      <ul className="flex flex-col p-1.5">
        {sources.map((source) => (
          <li
            key={source.id}
            data-status={source.status}
            className="flex items-center gap-3 rounded-kura-md px-2.5 py-2"
          >
            <span className="flex size-8 shrink-0 items-center justify-center rounded-kura-md bg-kura-surface-sunken text-kura-fg-muted shadow-kura-xs [&_svg]:size-4">
              {source.icon}
            </span>
            <span className="flex min-w-0 flex-1 flex-col">
              <span className="truncate font-medium text-[13px] text-kura-fg">{source.name}</span>
              <span className="truncate text-kura-fg-subtle text-xs">{source.detail}</span>
            </span>
            {source.status === "error" ? (
              <Button
                variant="outline"
                size="xs"
                aria-label={`Reconnect ${source.name}`}
                onClick={() => syncOne(source.id)}
              >
                <TriangleAlert className="text-kura-danger-text" />
                Reconnect
              </Button>
            ) : (
              <span className="inline-flex shrink-0 items-center gap-1.5 text-kura-fg-muted text-xs">
                {source.status === "syncing" ? (
                  <Spinner size="sm" label={null} />
                ) : (
                  <Check aria-hidden className="size-3.5 text-kura-success-text" />
                )}
                {source.status === "syncing" ? "Indexing…" : "Up to date"}
              </span>
            )}
          </li>
        ))}
      </ul>
    </section>
  );
}
```

## Dependencies

- npm: none
- Kura registry items: `kura-theme`, `utils`
- Related: `button`, `shimmer-text`, `thinking-indicator`

---

# Streaming Text

> Token-by-token model output with an even reveal cadence, word-group fade/blur-in and a soft caret. Takes a growing string or an async iterable.

- **Slug:** `streaming-text` · **Category:** conversation · **Status:** beta
- **Import:** `import { StreamingChunk, StreamingText, UseStreamingTextOptions, UseStreamingTextResult } from "@kura-ui/react/streaming-text";`
- **Docs:** https://kuro.abstergo.fyi/components/streaming-text
- **Registry item:** https://kuro.abstergo.fyi/r/streaming-text.json
- **Tags:** streaming, tokens, llm, text, typewriter, caret, chat, output

## Install

```bash
# shadcn registry (copies source into your project)
npx shadcn@latest add https://kuro.abstergo.fyi/r/streaming-text.json
# Kura CLI (same, plus dependency resolution and --json output)
npx @kura-ui/cli add streaming-text
# npm package
npm install @kura-ui/react
```

## When to use

- Render an LLM answer while it streams in (AI SDK, OpenAI/Anthropic SSE, a ReadableStream adapted to an async iterable).
- Smooth out bursty token delivery so text appears at a calm, even rhythm instead of in jumps.
- Show a live caret at the end of text that is still being generated.
- Build a custom renderer (markdown, rich text) on top of the `useStreamingText` hook exported from the same folder.

## When not to use

- Static text that is already complete — render it directly (StreamingText shows initial text instantly anyway).
- A “Thinking…” label before the first token — use shimmer-text (or reasoning for a collapsible trace).
- A full chat bubble with avatar and actions — use message, which composes streaming-text.
- Streaming code — use code-block with `streaming` so partial lines do not flicker.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `text` | `string` | — | no | The text received so far. Pass a growing string; a change that is not an append restarts the reveal from the common prefix. |
| `stream` | `AsyncIterable<string> \| null` | — | no | An async iterable of chunks (an async generator, AI SDK `textStream`). Takes precedence over `text`. Each iterable is consumed once and shared across re-renders. |
| `speed` | `number` | `90` | no | Minimum reveal cadence in characters per second. Bursts are buffered and released at this rate, faster when a backlog builds up (never more than ~½s behind). `0` disables smoothing. |
| `streaming` | `boolean` | — | no | More text is still coming: keeps the caret visible and `aria-busy` set. Defaults to true while `stream` is being read, otherwise false. |
| `onComplete` | `() => void` | — | no | Called once when the stream has ended and every character has been revealed (useful to enable message actions). |
| `animation` | `"blur" \| "fade" \| "none"` | `"blur"` | no | How each newly revealed word group enters: fade + 3px blur, fade only, or no animation. |
| `caret` | `boolean` | `true` | no | Show a soft pulsing caret at the live edge while streaming. It fades out (without reflow) when the stream completes. |

Native attributes of the root element, `className` and `ref` are passed through.

## Anatomy

- **StreamingText** (`data-slot="streaming-text"`) — Root, `white-space: pre-wrap`. `data-status="streaming" | "done"`, `aria-busy` while streaming.
- **Chunk** (`data-slot="streaming-text-chunk"`) — A recently revealed word group, animating in. Chunks merge into one text node ~0.7s after they appear, so long answers stay a single node.
- **Caret** (`data-slot="streaming-text-caret"`) — Decorative caret (aria-hidden). `data-visible` reflects streaming.

## Accessibility

- The text is real text in the DOM; the root sets `aria-busy` while streaming so a surrounding `role="log"` / live region announces the finished answer instead of every token.
- Do not make StreamingText itself a live region — put it inside message / a `role="log"` list.
- The caret is decorative (`aria-hidden`).
- Reduced motion: Word groups only fade in (no blur) and the caret stops pulsing; the even reveal cadence is kept because it carries meaning (text is still arriving).

## Notes for agents

- Pass the SAME iterable object across renders (store it in state/ref). Creating a new generator in JSX on every render restarts the stream.
- For a growing string, set `streaming` while tokens are still arriving; otherwise the caret hides and `onComplete` fires each time the reveal catches up.
- Text present at mount renders instantly — remounting or hydrating a finished message never replays the animation.
- For markdown, call `useStreamingText({ stream })` and feed `displayed` to your markdown renderer (or render `settled` + `chunks` yourself to keep the per-chunk fade).
- Import the hook from the same entry: `import { StreamingText, useStreamingText } from "@kura-ui/react/streaming-text"`.

## Examples

### Async iterable (minimal)

Pass a token generator; bursty delivery is evened out automatically.

```tsx
"use client";

import * as React from "react";
import { StreamingText } from "@kura-ui/react/streaming-text";

const ANSWER =
  "Streaming feels calm when the reveal keeps an even rhythm. Tokens arrive in bursts — three at once, then a pause — so Kura buffers them and releases whole words at a steady cadence, fading each group in while the caret holds the live edge.";

async function* fakeTokens(text: string, signal?: AbortSignal): AsyncGenerator<string> {
  const words = text.split(/(?<=\s)/);
  for (let i = 0; i < words.length; ) {
    if (signal?.aborted) return;
    const n = 1 + Math.floor(Math.random() * 4);
    yield words.slice(i, i + n).join("");
    i += n;
    await new Promise((r) => setTimeout(r, Math.random() < 0.15 ? 380 : 40 + Math.random() * 90));
  }
}

export function StreamingTextMinimal() {
  const [stream] = React.useState(() => fakeTokens(ANSWER));
  return <StreamingText stream={stream} className="max-w-md" />;
}
```

### Growing string, every prop (full)

Drive it with a growing `text` + `streaming`, tune `speed`, and react to `onComplete`.

```tsx
"use client";

import { RotateCcw } from "lucide-react";
import * as React from "react";
import { Button } from "@kura-ui/react/button";
import { StreamingText } from "@kura-ui/react/streaming-text";

const ANSWER =
  "Streaming feels calm when the reveal keeps an even rhythm. Tokens arrive in bursts — three at once, then a pause — so Kura buffers them and releases whole words at a steady cadence, fading each group in while the caret holds the live edge.";

async function* fakeTokens(text: string, signal?: AbortSignal): AsyncGenerator<string> {
  const words = text.split(/(?<=\s)/);
  for (let i = 0; i < words.length; ) {
    if (signal?.aborted) return;
    const n = 1 + Math.floor(Math.random() * 4);
    yield words.slice(i, i + n).join("");
    i += n;
    await new Promise((r) => setTimeout(r, Math.random() < 0.15 ? 380 : 40 + Math.random() * 90));
  }
}

export function StreamingTextFull() {
  const [run, setRun] = React.useState(0);
  const [text, setText] = React.useState("");
  const [streaming, setStreaming] = React.useState(true);
  const [done, setDone] = React.useState(0);

  // biome-ignore lint/correctness/useExhaustiveDependencies: `run` restarts the fake stream
  React.useEffect(() => {
    const controller = new AbortController();
    setText("");
    setStreaming(true);
    (async () => {
      let acc = "";
      for await (const token of fakeTokens(ANSWER, controller.signal)) {
        acc += token;
        setText(acc);
      }
      if (!controller.signal.aborted) setStreaming(false);
    })();
    return () => controller.abort();
  }, [run]);

  return (
    <div className="flex w-full max-w-md flex-col gap-4">
      <StreamingText
        text={text}
        streaming={streaming}
        speed={120}
        animation="blur"
        caret
        onComplete={() => setDone((d) => d + 1)}
        className="min-h-32"
      />
      <div className="flex items-center justify-between">
        <span className="font-kura-mono text-kura-fg-subtle text-xs tabular-nums">
          {text.length} chars · completed {done}×
        </span>
        <Button variant="secondary" size="sm" onClick={() => setRun((r) => r + 1)}>
          <RotateCcw /> Replay
        </Button>
      </div>
    </div>
  );
}
```

### Custom renderer with useStreamingText (composition)

Shimmering “Thinking…” until the first token, then a hand-rolled renderer built on the hook, with a Stop button.

```tsx
"use client";

import { Square } from "lucide-react";
import * as React from "react";
import { Button } from "@kura-ui/react/button";
import { ShimmerText } from "@kura-ui/react/shimmer-text";
import { useStreamingText } from "@kura-ui/react/streaming-text";

const ANSWER =
  "Streaming feels calm when the reveal keeps an even rhythm. Tokens arrive in bursts — three at once, then a pause — so Kura buffers them and releases whole words at a steady cadence, fading each group in while the caret holds the live edge.";

async function* fakeTokens(text: string, signal?: AbortSignal): AsyncGenerator<string> {
  const words = text.split(/(?<=\s)/);
  for (let i = 0; i < words.length; ) {
    if (signal?.aborted) return;
    const n = 1 + Math.floor(Math.random() * 4);
    yield words.slice(i, i + n).join("");
    i += n;
    await new Promise((r) => setTimeout(r, Math.random() < 0.15 ? 380 : 40 + Math.random() * 90));
  }
}

export function StreamingTextComposition() {
  const [stream, setStream] = React.useState<AsyncIterable<string> | null>(null);
  const [stopped, setStopped] = React.useState(false);
  const controller = React.useRef<AbortController | null>(null);

  React.useEffect(() => {
    const id = setTimeout(() => {
      controller.current = new AbortController();
      setStream(fakeTokens(ANSWER, controller.current.signal));
    }, 1200);
    return () => {
      clearTimeout(id);
      controller.current?.abort();
    };
  }, []);

  const { settled, chunks, isStreaming } = useStreamingText({ stream });
  const waiting = !stream;

  return (
    <div className="flex w-full max-w-md flex-col gap-3 rounded-kura-xl bg-kura-surface p-4 shadow-kura-sm">
      <div className="flex h-6 items-center justify-between">
        <span className="font-medium text-kura-fg text-sm">Assistant</span>
        {(waiting || isStreaming) && !stopped && (
          <Button
            variant="ghost"
            size="xs"
            onClick={() => {
              controller.current?.abort();
              setStopped(true);
            }}
          >
            <Square className="fill-current" /> Stop
          </Button>
        )}
      </div>
      {waiting ? (
        <p role="status" className="text-[15px] leading-relaxed">
          <ShimmerText>Thinking…</ShimmerText>
        </p>
      ) : (
        <p
          aria-busy={isStreaming || undefined}
          className="whitespace-pre-wrap text-[15px] text-kura-fg leading-relaxed"
        >
          {settled}
          {chunks.map((c) => (
            <span
              key={c.id}
              className="transition-opacity duration-(--kura-duration-slow) starting:opacity-0"
            >
              {c.text}
            </span>
          ))}
        </p>
      )}
    </div>
  );
}
```

## Dependencies

- npm: none
- Kura registry items: `kura-theme`, `utils`
- Related: `message`, `reasoning`, `code-block`, `shimmer-text`

---

# Thinking Indicator

> Compact AI “thinking” indicators — dots, pulse, orbit, wave, or cycling status text — inside a polite live region.

- **Slug:** `thinking-indicator` · **Category:** feedback · **Status:** beta
- **Import:** `import { ThinkingIndicator } from "@kura-ui/react/thinking-indicator";`
- **Docs:** https://kuro.abstergo.fyi/components/thinking-indicator
- **Registry item:** https://kuro.abstergo.fyi/r/thinking-indicator.json
- **Tags:** loading, thinking, typing, dots, status, indicator, pending, ai

## Install

```bash
# shadcn registry (copies source into your project)
npx shadcn@latest add https://kuro.abstergo.fyi/r/thinking-indicator.json
# Kura CLI (same, plus dependency resolution and --json output)
npx @kura-ui/cli add thinking-indicator
# npm package
npm install @kura-ui/react
```

## When to use

- The assistant has received a prompt but not produced its first token yet.
- A pending assistant message bubble or a placeholder row in a chat list.
- Cycling short status lines while an agent works: “Searching…”, “Reading 4 files…” (variant text).
- A tiny inline signal next to a label, tab or button that work is in progress.

## When not to use

- Shimmering an existing label in place — use shimmer-text.
- Network or file loading that is not model thinking — use spinner.
- A whole container being worked on — use border-beam.
- A voice agent's state — use agent-orb.
- Streaming the answer itself — use streaming-text.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `variant` | `"dots" \| "pulse" \| "orbit" \| "wave" \| "text"` | `"dots"` | no | dots: three bouncing dots (staggered spring). pulse: a breathing dot with an expanding ring. orbit: two dots chasing round a track. wave: four equaliser bars. text: a pulse plus shimmering status text that cycles through `messages`. |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | no | Dot size 4 / 6 / 8 px; text 12 / 14 / 15 px. |
| `label` | `string` | `"Thinking"` | no | Accessible status text. Announced once when the indicator mounts or the label changes — never on each animation cycle. |
| `messages` | `readonly string[]` | — | no | Status lines for the text variant. Several lines cycle with a cross-fade (and only `label` is announced); a single line is shown and announced as is — update it as the agent progresses. |
| `interval` | `number` | `2400` | no | Milliseconds each message stays up when cycling (minimum 600). |

Native attributes of the root element, `className` and `ref` are passed through.

## Anatomy

- **ThinkingIndicator** (`data-slot="thinking-indicator"`) — Inline root with role=status. `data-variant` and `data-size` mirror the props. Colour is currentColor (text-kura-accent by default).
- **Shape** (`data-slot="thinking-indicator-shape"`) — The animated glyph (aria-hidden).
- **Text** (`data-slot="thinking-indicator-text"`) — Text variant only: all messages stacked in one grid cell (width = widest message, so no layout shift); the active one has data-active=true.

## Accessibility

- Role: `status`
- role=status + aria-live=polite: screen readers hear the label once, politely, not a stream of updates.
- Shapes are aria-hidden; a visually hidden label carries the meaning.
- When several messages cycle, the cycling text is aria-hidden and only `label` is announced, so the live region does not spam.
- Colour is not the only signal: the text variant and the label describe the state.
- Reduced motion: Loops stop. Dots show three static dots of rising opacity, the pulse is a still dot, orbit freezes with both dots visible, wave shows static bars of varied heights. Text still cycles but with an opacity cross-fade only (no blur, no rise, no shimmer).

## Notes for agents

- Recolour with a text class (`className="text-kura-fg-subtle"`); shapes use currentColor. Keep the jade default when it means “the model is working”.
- Replace the indicator with the streamed message once the first token arrives; do not show both.
- For real progress, pass one message and update it (`messages={[step]}`) — each change is announced. For ambient variety, pass several and let them cycle.
- Keep messages short (≤ 5 words) and end with an ellipsis.

## Examples

### Thinking dots (minimal)

```tsx
import { ThinkingIndicator } from "@kura-ui/react/thinking-indicator";

export function ThinkingIndicatorMinimal() {
  return <ThinkingIndicator />;
}
```

### Every variant and size (full)

dots, pulse, orbit and wave at sm/md/lg, cycling text, and a muted recolour.

```tsx
import * as React from "react";
import {
  ThinkingIndicator,
  type ThinkingIndicatorSize,
  type ThinkingIndicatorVariant,
} from "@kura-ui/react/thinking-indicator";

const variants: ThinkingIndicatorVariant[] = ["dots", "pulse", "orbit", "wave"];

const sizes: ThinkingIndicatorSize[] = ["sm", "md", "lg"];

export function ThinkingIndicatorFull() {
  return (
    <div className="flex w-full max-w-lg flex-col gap-6">
      <div className="grid grid-cols-[auto_repeat(3,1fr)] items-center gap-x-6 gap-y-4 text-kura-fg-subtle text-xs">
        <span />
        {sizes.map((s) => (
          <span key={s} className="font-kura-mono">
            {s}
          </span>
        ))}
        {variants.map((v) => (
          <React.Fragment key={v}>
            <span className="font-kura-mono">{v}</span>
            {sizes.map((s) => (
              <span key={s} className="flex h-6 items-center">
                <ThinkingIndicator variant={v} size={s} label={`Thinking (${v}, ${s})`} />
              </span>
            ))}
          </React.Fragment>
        ))}
      </div>
      <div className="flex flex-col gap-3 border-kura-border-subtle border-t pt-5">
        <ThinkingIndicator
          variant="text"
          label="Researching"
          messages={["Searching the web…", "Reading 4 files…", "Comparing 12 sources…"]}
          interval={2200}
        />
        <ThinkingIndicator variant="dots" size="sm" className="text-kura-fg-subtle" />
      </div>
    </div>
  );
}
```

### Pending assistant message (composition)

Text variant inside a message bubble with a Stop Button.

```tsx
"use client";

import { Bot } from "lucide-react";
import * as React from "react";
import { Button } from "@kura-ui/react/button";
import { ThinkingIndicator } from "@kura-ui/react/thinking-indicator";

export function ThinkingIndicatorInMessage() {
  const [stopped, setStopped] = React.useState(false);
  return (
    <div className="flex w-full max-w-md items-start gap-3">
      <span className="flex size-7 shrink-0 items-center justify-center rounded-full bg-kura-accent-subtle text-kura-accent-text">
        <Bot className="size-3.5" aria-hidden />
      </span>
      <div className="flex min-w-0 flex-1 flex-col gap-2 rounded-kura-xl bg-kura-surface px-4 py-3 shadow-kura-sm">
        {stopped ? (
          <p className="text-kura-fg-muted text-sm">Stopped. Ask again whenever you're ready.</p>
        ) : (
          <ThinkingIndicator
            variant="text"
            label="Assistant is working"
            messages={["Planning the migration…", "Reading schema.prisma…", "Drafting SQL…"]}
          />
        )}
        <div className="flex justify-end">
          <Button size="xs" variant="ghost" onClick={() => setStopped((s) => !s)}>
            {stopped ? "Retry" : "Stop"}
          </Button>
        </div>
      </div>
    </div>
  );
}
```

## Dependencies

- npm: none
- Kura registry items: `kura-theme`, `shimmer-text`, `utils`
- Related: `shimmer-text`, `spinner`, `border-beam`, `agent-orb`, `streaming-text`, `message`

---

# Tool Call

> One tool invocation: name and icon, queued/running/done/failed/awaiting-approval status, live elapsed time and collapsible JSON args and result.

- **Slug:** `tool-call` · **Category:** agent · **Status:** beta
- **Import:** `import { ToolCall, ToolCallStatus } from "@kura-ui/react/tool-call";`
- **Docs:** https://kuro.abstergo.fyi/components/tool-call
- **Registry item:** https://kuro.abstergo.fyi/r/tool-call.json
- **Tags:** tool, function-calling, agent, mcp, status, json, timer, collapsible

## Install

```bash
# shadcn registry (copies source into your project)
npx shadcn@latest add https://kuro.abstergo.fyi/r/tool-call.json
# Kura CLI (same, plus dependency resolution and --json output)
npx @kura-ui/cli add tool-call
# npm package
npm install @kura-ui/react
```

## When to use

- Show a function/tool call an LLM made (AI SDK tool parts, MCP calls, OpenAI/Anthropic tool_use blocks) inside an assistant message.
- Show a tool's progress with a live timer, then its result or error.
- A tool that needs the user's go-ahead: status="awaiting-approval" with Approve/Deny buttons in `actions`.
- Compact inline mentions of tool use within answer text (variant="inline").

## When not to use

- A multi-step plan with many steps and progress — use agent-timeline (put ToolCalls inside steps if needed).
- A dedicated, prominent permission request with risk level and keyboard shortcuts — use approval-prompt.
- Plain code output — use code-block.
- Model thinking — use reasoning.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `name` | `string` | — | yes | Tool identifier, e.g. "search_web". Rendered in mono when no `title` is given; also used in the status announcement. |
| `title` | `React.ReactNode` | — | no | Human label, e.g. "Searching the web" → "Searched the web". Replaces `name` visually. |
| `icon` | `React.ReactNode` | — | no | Tool icon (lucide), e.g. <Globe />. Default a wrench. |
| `status` | `"pending" \| "running" \| "success" \| "error" \| "awaiting-approval"` | `"running"` | no | Lifecycle. pending = hollow ring; running = jade pulse + shimmering title + ticking timer; success = check; error = cross (details open by default); awaiting-approval = jade hand. |
| `args` | `unknown` | — | no | Arguments. Objects are pretty-printed JSON with syntax tint (CodeBlock); strings render as-is. |
| `result` | `unknown` | — | no | Output. Objects are pretty-printed JSON; strings render as-is. Long values collapse at 220px with “Show N more lines”. |
| `error` | `React.ReactNode` | — | no | Error message for status="error", shown in a danger panel in the details. |
| `summary` | `React.ReactNode` | — | no | One-line summary next to the title (truncated). Default: the first primitive value in `args`. Pass null to hide. |
| `startedAt` | `Date \| number` | — | no | Start time for the live timer (e.g. from the server). Default: when status became running. |
| `duration` | `number` | — | no | Final duration in ms (persisted calls). Default: measured from running → success/error. |
| `variant` | `"card" \| "inline"` | `"card"` | no | card = bordered card; inline = compact borderless row for use inside message text. |
| `open` | `boolean` | — | no | Details expanded (controlled). |
| `defaultOpen` | `boolean` | — | no | Initial expanded state when uncontrolled. Default true for "error" and "awaiting-approval". |
| `onOpenChange` | `(open: boolean) => void` | — | no | Called when details are toggled. |
| `actions` | `React.ReactNode` | — | no | Always-visible footer row (right-aligned), e.g. Deny / Approve buttons. |

Native attributes of the root element, `className` and `ref` are passed through.

## Anatomy

- **ToolCall** (`data-slot="tool-call"`) — `data-status`, `data-variant`, `data-state="open" | "closed"` (when it has details).
- **Trigger** (`data-slot="tool-call-trigger"`) — Header row; a button with aria-expanded when there are details.
- **Status** (`data-slot="tool-call-status"`) — 20px status glyph (aria-hidden).
- **Icon** (`data-slot="tool-call-icon"`) — Tool icon (aria-hidden).
- **Title** (`data-slot="tool-call-title"`) — Title or mono name; shimmers while running.
- **Summary** (`data-slot="tool-call-summary"`) — Truncated one-line summary.
- **Elapsed** (`data-slot="tool-call-elapsed"`) — Mono tabular duration: 180ms, 1.5s, 1m 5s.
- **Details** (`data-slot="tool-call-details"`) — Collapsible args/error/result (grid-rows transition, inert when closed).
- **Section** (`data-slot="tool-call-section"`) — “Arguments” / “Result” label + headerless CodeBlock.
- **Error** (`data-slot="tool-call-error"`) — Danger panel with the error message.
- **Actions** (`data-slot="tool-call-actions"`) — Footer for `actions`.

## Accessibility

- The header is a button (aria-expanded/aria-controls) only when there is something to expand.
- Each call has a polite status region (“search_web Running” → “search_web Completed”); the ticking timer is not announced.
- Status is conveyed by text for screen readers, not only by colour/icon.
- Collapsed details are inert; JSON panes are keyboard-scrollable regions named “Arguments code” / “Result code”.
- Reduced motion: The running pulse and title shimmer stop; the chevron and details change without travel (fade only).

| Keys | Action |
| --- | --- |
| Enter / Space | Expand or collapse the details |
| Tab | Into the JSON panes and footer actions |

## Notes for agents

- Map AI SDK tool part states: input-streaming → pending, input-available → running, output-available → success, output-error → error.
- Keep the same ToolCall mounted across states so the measured timer works; for history, pass `duration` (ms).
- Swap `title` between present and past tense (“Searching…” → “Searched the web”) as the status changes.
- args/result accept any JSON-serializable value; circular objects fall back to String().

## Examples

### Finished call (minimal)

Name, args and a string result.

```tsx
import { ToolCall } from "@kura-ui/react/tool-call";

export function ToolCallMinimal() {
  return (
    <ToolCall
      name="read_file"
      status="success"
      duration={182}
      args={{ path: "src/app/page.tsx" }}
      result="export default function Page() {\n  return <Chat />;\n}"
      className="w-full max-w-lg"
    />
  );
}
```

### Live lifecycle (full)

pending → running (shimmer + timer) → success with a JSON result; controlled open state.

```tsx
"use client";

import { Globe, RotateCcw } from "lucide-react";
import * as React from "react";
import { Button } from "@kura-ui/react/button";
import { ToolCall, type ToolCallStatus } from "@kura-ui/react/tool-call";

const RESULT = {
  results: [
    { title: "useOptimistic – React", url: "https://react.dev/reference/react/useOptimistic" },
    { title: "Server Actions and Mutations", url: "https://nextjs.org/docs/app/guides/forms" },
  ],
  took_ms: 412,
};

export function ToolCallFull() {
  const [status, setStatus] = React.useState<ToolCallStatus>("pending");
  const [open, setOpen] = React.useState(false);
  const [run, setRun] = React.useState(0);

  // biome-ignore lint/correctness/useExhaustiveDependencies: `run` replays the lifecycle
  React.useEffect(() => {
    setStatus("pending");
    const a = setTimeout(() => setStatus("running"), 700);
    const b = setTimeout(() => setStatus("success"), 3100);
    return () => {
      clearTimeout(a);
      clearTimeout(b);
    };
  }, [run]);

  return (
    <div className="flex w-full max-w-lg flex-col items-start gap-3">
      <ToolCall
        name="search_web"
        title={status === "success" ? "Searched the web" : "Searching the web"}
        icon={<Globe />}
        status={status}
        args={{ query: "react useOptimistic rollback", max_results: 2 }}
        result={status === "success" ? RESULT : undefined}
        summary="react useOptimistic rollback"
        variant="card"
        open={open}
        onOpenChange={setOpen}
        className="w-full"
      />
      <Button variant="secondary" size="sm" onClick={() => setRun((r) => r + 1)}>
        <RotateCcw /> Replay
      </Button>
    </div>
  );
}
```

### All states (state)

Queued, running, done and failed.

```tsx
import { FileText, Terminal } from "lucide-react";
import { ToolCall } from "@kura-ui/react/tool-call";

export function ToolCallStates() {
  return (
    <div className="flex w-full max-w-lg flex-col gap-2">
      <ToolCall name="list_files" status="pending" args={{ dir: "src/components" }} />
      <ToolCall
        name="run_tests"
        icon={<Terminal />}
        status="running"
        args={{ filter: "message" }}
      />
      <ToolCall
        name="read_file"
        icon={<FileText />}
        status="success"
        duration={96}
        args={{ path: "README.md" }}
        result="# Kura UI"
      />
      <ToolCall
        name="deploy_preview"
        status="error"
        duration={4210}
        args={{ branch: "feat/message" }}
        error="Error: build failed — Type error in message.tsx:295"
        defaultOpen={false}
      />
    </div>
  );
}
```

### Inline (variant)

A compact row inside answer text.

```tsx
import { Globe } from "lucide-react";
import { ToolCall } from "@kura-ui/react/tool-call";

export function ToolCallInline() {
  return (
    <div className="flex w-full max-w-lg flex-col gap-2 text-[15px] text-kura-fg leading-relaxed">
      <p>I checked the docs before answering:</p>
      <ToolCall
        variant="inline"
        name="fetch_url"
        title="Read react.dev"
        icon={<Globe />}
        status="success"
        duration={640}
        args={{ url: "https://react.dev/reference/react/useOptimistic" }}
        result={{ status: 200, bytes: 48213 }}
      />
      <p>The hook drops the optimistic value automatically when the action throws.</p>
    </div>
  );
}
```

### Awaiting approval (composition)

Approve/Deny Buttons in the actions footer resolve the call.

```tsx
"use client";

import { Terminal } from "lucide-react";
import * as React from "react";
import { Button } from "@kura-ui/react/button";
import { ToolCall, type ToolCallStatus } from "@kura-ui/react/tool-call";

export function ToolCallApproval() {
  const [status, setStatus] = React.useState<ToolCallStatus>("awaiting-approval");
  return (
    <ToolCall
      name="run_command"
      title="Run a shell command"
      icon={<Terminal />}
      status={status}
      args={{ command: "pnpm db:migrate --env production" }}
      result={status === "success" ? "Applied 3 migrations." : undefined}
      duration={status === "success" ? 1830 : undefined}
      className="w-full max-w-lg"
      actions={
        status === "awaiting-approval" ? (
          <>
            <Button variant="ghost" size="sm" onClick={() => setStatus("error")}>
              Deny
            </Button>
            <Button size="sm" onClick={() => setStatus("success")}>
              Approve
            </Button>
          </>
        ) : undefined
      }
      error={status === "error" ? "Denied by user." : undefined}
    />
  );
}
```

## Dependencies

- npm: `lucide-react`
- Kura registry items: `kura-theme`, `code-block`, `shimmer-text`, `use-controllable-state`, `utils`
- Related: `agent-timeline`, `approval-prompt`, `code-block`, `reasoning`, `message`

---

# Tooltip

> Short label on hover or focus with an optional shortcut, origin-aware motion and instant skip between tooltips.

- **Slug:** `tooltip` · **Category:** primitives · **Status:** stable
- **Import:** `import { Tooltip, TooltipContent, TooltipProvider, TooltipRoot, TooltipTrigger } from "@kura-ui/react/tooltip";`
- **Docs:** https://kuro.abstergo.fyi/components/tooltip
- **Registry item:** https://kuro.abstergo.fyi/r/tooltip.json
- **Tags:** tooltip, hint, label, hover, overlay

## Install

```bash
# shadcn registry (copies source into your project)
npx shadcn@latest add https://kuro.abstergo.fyi/r/tooltip.json
# Kura CLI (same, plus dependency resolution and --json output)
npx @kura-ui/cli add tooltip
# npm package
npm install @kura-ui/react
```

## When to use

- Name an icon-only control or reveal its shortcut.
- Brief supplementary hints (a few words).

## When not to use

- Interactive or rich content (links, buttons, forms) — use popover.
- Essential information — it is invisible on touch devices; put it in the UI.
- Labelling icon buttons — icon-button already includes a tooltip.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `content` | `React.ReactNode` | — | yes | The label. Keep it to a few words. |
| `children` | `React.ReactElement` | — | yes | The trigger: one focusable element that accepts a ref. |
| `shortcut` | `readonly KeyName[]` | — | no | Keys shown after the label, e.g. ["mod", "enter"]. |
| `side` | `"top" \| "right" \| "bottom" \| "left"` | `"top"` | no | Preferred side. |
| `align` | `"start" \| "center" \| "end"` | `"center"` | no | Alignment on that side. |
| `delayDuration` | `number` | `500` | no | Hover delay in ms before opening. Inside a TooltipProvider, defaults to the provider's. |
| `disabled` | `boolean` | `false` | no | Render only the trigger. |
| `contentClassName` | `string` | — | no | Classes for the floating bubble. |

Native attributes of the root element, `className` and `ref` are passed through.

## Anatomy

- **TooltipProvider** — Optional shared provider so moving between tooltips skips the delay.
- **TooltipRoot** — Radix Root, for fully custom compositions.
- **TooltipTrigger** — Radix Trigger.
- **TooltipContent** (`data-slot="tooltip-content"`) — Styled floating bubble; accepts `shortcut`.
  - `shortcut`: `readonly KeyName[]` — Keys shown after the label.

## Accessibility

- Role: `tooltip`
- Opens on hover after a delay and immediately on keyboard focus; the trigger gets aria-describedby.
- Never the only way to reach information; not shown on touch.
- Reduced motion: Scale and travel are removed; only a fast fade remains.

| Keys | Action |
| --- | --- |
| Tab | Focus the trigger and open |
| Escape | Close |

## Notes for agents

- The child must forward refs and accept event props (Kura Button/IconButton do). Wrap plain text in a <button>.
- <Tooltip> (and IconButton) creates its own provider only when standalone; inside a <TooltipProvider> it joins it, so wrapping a toolbar in TooltipProvider makes moving between sibling tooltips instant.

## Examples

### Basic (minimal)

```tsx
import { Button } from "@kura-ui/react/button";
import { Tooltip } from "@kura-ui/react/tooltip";

export function TooltipMinimal() {
  return (
    <Tooltip content="Copy to clipboard">
      <Button variant="secondary">Hover me</Button>
    </Tooltip>
  );
}
```

### Shortcut, sides and shared provider (full)

```tsx
import { Button } from "@kura-ui/react/button";
import { Tooltip, TooltipProvider } from "@kura-ui/react/tooltip";

export function TooltipFull() {
  return (
    <TooltipProvider>
      <div className="flex items-center gap-2">
        <Tooltip content="Send message" shortcut={["mod", "enter"]} side="top">
          <Button variant="secondary" size="sm">
            Top
          </Button>
        </Tooltip>
        <Tooltip
          content="New chat"
          shortcut={["mod", "shift", "o"]}
          side="bottom"
          delayDuration={200}
        >
          <Button variant="secondary" size="sm">
            Bottom
          </Button>
        </Tooltip>
        <Tooltip content="Disabled tooltip" disabled>
          <Button variant="ghost" size="sm">
            No tooltip
          </Button>
        </Tooltip>
      </div>
    </TooltipProvider>
  );
}
```

### Editor toolbar with shared delay (composition)

Tooltip parts under one TooltipProvider, so moving across the formatting toolbar skips the open delay.

```tsx
"use client";

import { Bold, Cloud, Code, Italic, Link, PenLine, Redo2, Undo2 } from "lucide-react";
import * as React from "react";
import { Button } from "@kura-ui/react/button";
import { TooltipContent, TooltipProvider, TooltipRoot, TooltipTrigger } from "@kura-ui/react/tooltip";

const formatTools = [
  { id: "bold", label: "Bold", icon: <Bold />, shortcut: ["mod", "b"] },
  { id: "italic", label: "Italic", icon: <Italic />, shortcut: ["mod", "i"] },
  { id: "code", label: "Inline code", icon: <Code />, shortcut: ["mod", "e"] },
  { id: "link", label: "Link", icon: <Link />, shortcut: ["mod", "k"] },
] as const;

function ToolbarTip({
  label,
  shortcut,
  side = "top",
  children,
}: {
  label: string;
  shortcut?: readonly string[];
  side?: "top" | "bottom";
  children: React.ReactElement;
}) {
  return (
    <TooltipRoot>
      <TooltipTrigger asChild>{children}</TooltipTrigger>
      <TooltipContent side={side} shortcut={shortcut}>
        {label}
      </TooltipContent>
    </TooltipRoot>
  );
}

const square = "size-7 px-0";

export function TooltipEditorToolbar() {
  const [active, setActive] = React.useState<string[]>(["bold"]);
  const toggle = (id: string) =>
    setActive((a) => (a.includes(id) ? a.filter((x) => x !== id) : [...a, id]));

  return (
    <TooltipProvider delayDuration={400}>
      <div className="flex w-full max-w-xl flex-col overflow-hidden rounded-kura-xl bg-kura-surface shadow-kura-sm">
        <div
          role="toolbar"
          aria-label="Formatting"
          className="flex items-center gap-0.5 border-kura-border-subtle border-b px-2 py-1.5"
        >
          <ToolbarTip label="Undo" shortcut={["mod", "z"]}>
            <Button variant="ghost" size="sm" aria-label="Undo" className={square}>
              <Undo2 />
            </Button>
          </ToolbarTip>
          <ToolbarTip label="Redo" shortcut={["mod", "shift", "z"]}>
            <Button variant="ghost" size="sm" aria-label="Redo" className={square}>
              <Redo2 />
            </Button>
          </ToolbarTip>
          <span aria-hidden className="mx-1 h-4 w-px bg-kura-border" />
          {formatTools.map((tool) => (
            <ToolbarTip key={tool.id} label={tool.label} shortcut={tool.shortcut}>
              <Button
                variant="ghost"
                size="sm"
                aria-label={tool.label}
                aria-pressed={active.includes(tool.id)}
                onClick={() => toggle(tool.id)}
                className={`${square} aria-pressed:bg-kura-active aria-pressed:text-kura-fg`}
              >
                {tool.icon}
              </Button>
            </ToolbarTip>
          ))}
          <span aria-hidden className="mx-1 h-4 w-px bg-kura-border" />
          <ToolbarTip label="Rewrite the selection" shortcut={["mod", "j"]}>
            <Button variant="ghost" size="sm">
              <PenLine />
              Rewrite
            </Button>
          </ToolbarTip>
          <div className="ml-auto flex items-center">
            <ToolbarTip label="Saved 12:04 · version 18" side="bottom">
              <button
                type="button"
                className="inline-flex h-7 cursor-default items-center gap-1.5 rounded-kura-sm px-2 text-kura-fg-subtle text-xs outline-none focus-visible:shadow-kura-focus"
              >
                <Cloud className="size-3.5" aria-hidden />
                Saved
              </button>
            </ToolbarTip>
          </div>
        </div>
        <p className="px-4 py-3.5 text-[15px] text-kura-fg leading-relaxed">
          <strong className="font-semibold">Launch note:</strong> the new composer ships behind the{" "}
          <code className="rounded-kura-xs bg-kura-surface-sunken px-1 py-0.5 font-kura-mono text-[13px]">
            composer_v2
          </code>{" "}
          flag on Thursday, starting with 10% of workspaces.
        </p>
      </div>
    </TooltipProvider>
  );
}
```

## Dependencies

- npm: `radix-ui`
- Kura registry items: `kura-theme`, `kbd`, `kura-keys`, `utils`
- Related: `icon-button`, `popover`, `kbd`

---

# Voice Dictation

> Mic button that expands into a live waveform pill with a timer and live transcript; speech-to-text with recording fallback, toggle or hold-to-talk.

- **Slug:** `voice-dictation` · **Category:** voice · **Status:** experimental
- **Import:** `import { VoiceDictation, VoiceDictationStatus } from "@kura-ui/react/voice-dictation";`
- **Docs:** https://kuro.abstergo.fyi/components/voice-dictation
- **Registry item:** https://kuro.abstergo.fyi/r/voice-dictation.json
- **Tags:** voice, dictation, speech-to-text, microphone, push-to-talk, transcription, waveform

## Install

```bash
# shadcn registry (copies source into your project)
npx shadcn@latest add https://kuro.abstergo.fyi/r/voice-dictation.json
# Kura CLI (same, plus dependency resolution and --json output)
npx @kura-ui/cli add voice-dictation
# npm package
npm install @kura-ui/react
```

## When to use

- Let users dictate a prompt instead of typing — standalone or in a composer toolbar.
- Push-to-talk input (mode="hold") for voice notes or quick commands.
- Browsers without the Web Speech API: record audio and transcribe on your server via `transcribe`.

## When not to use

- A full-duplex conversation with a voice agent (barge-in, spoken replies) — use agent-orb with your realtime session.
- Only visualising audio you already have — use audio-waveform.
- Typing prompts — use composer.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `onTranscript` | `(text: string) => void` | — | no | Called once per dictation with the final trimmed text. Not called when cancelled (× or Escape) or when nothing was heard. |
| `onInterim` | `(text: string) => void` | — | no | Live text (final + interim) while listening, e.g. to preview in a placeholder. |
| `onStatusChange` | `(status: VoiceDictationStatus) => void` | — | no | idle \| requesting \| listening \| processing \| denied \| unsupported \| error. |
| `mode` | `"toggle" \| "hold"` | `"toggle"` | no | toggle = click to start/stop; hold = dictate while the pointer, Space/Enter or the hotkey is held. |
| `hotkey` | `readonly KeyName[] \| null` | `["mod", "shift", "d"]` | no | Global shortcut (works while typing). null disables it. |
| `lang` | `string` | — | no | BCP-47 language for recognition, e.g. "en-US". Defaults to the page language. |
| `transcribe` | `(audio: Blob) => Promise<string>` | — | no | Fallback transcription when the Web Speech API is missing (Firefox): receives the recording; status is “processing” until it resolves. |
| `simulate` | `boolean \| string` | — | no | Demo mode: fake permission, simulated waveform and a scripted transcript (a string is typed out word by word). For docs and tests. |
| `showTranscript` | `boolean` | `true` | no | Show the live transcript card under the control. Turn off inside a composer. |
| `transcriptPlaceholder` | `string` | `"Listening…"` | no | Text in the transcript card before words arrive. |
| `disabled` | `boolean` | `false` | no | Disable the control. |

Native attributes of the root element, `className` and `ref` are passed through.

## Anatomy

- **VoiceDictation** (`data-slot="voice-dictation"`) — Root column. data-status (see onStatusChange) and data-mode.
- **VoiceDictationControl** (`data-slot="voice-dictation-control"`) — The mic button; while live it grows (layout spring) into a signal-tinted pill with waveform, timer and cancel.
- **VoiceDictationButton** (`data-slot="voice-dictation-button"`) — Mic / stop / mic-off button with aria-pressed and a tooltip showing the hotkey.
- **VoiceDictationCancel** (`data-slot="voice-dictation-cancel"`) — × button that discards the dictation.
- **VoiceDictationTranscript** (`data-slot="voice-dictation-transcript"`) — Live transcript: final words in ink, interim words subtle, a signal caret while listening.
- **VoiceDictationMessage** (`data-slot="voice-dictation-message"`) — Recovery text for denied / unsupported / error.

## Accessibility

- The button is labelled “Dictate” (or “Hold to dictate”) with aria-pressed reflecting listening; the stop/mic icon swap is visual only.
- A visually hidden role=status announces state changes once (“Listening”, “Transcribing”, “Microphone access is blocked”) — never per word.
- Denied and unsupported states keep a visible text explanation and the button stays reachable to retry.
- The waveform is decorative (aria-hidden); the timer is plain text with tabular numbers.
- Reduced motion: The pill appears without the layout spring, icon swaps fade without scale or blur, the waveform becomes a slow level meter and the caret stops blinking.

| Keys | Action |
| --- | --- |
| Enter / Space | Toggle dictation (hold them in hold mode) |
| Mod+Shift+D | Global toggle / hold (configurable via hotkey) |
| Escape | Cancel and discard while listening |

## Notes for agents

- In docs, demos and tests pass `simulate` — real recognition needs a user gesture, mic permission and (for Chrome) a network connection.
- Feed a Composer by controlling its value: onTranscript={(t) => setValue((v) => (v ? v + ' ' + t : t))}; pass showTranscript={false}.
- Provide `transcribe` for Firefox/other browsers without SpeechRecognition; without it those browsers record but emit nothing.
- Only one mounted instance should own a given hotkey; pass hotkey={null} on the others.
- The listening pill uses the jade signal — avoid another accent-filled element in the same view while dictating.

## Examples

### Toggle with live transcript (minimal)

```tsx
"use client";

import { VoiceDictation } from "@kura-ui/react/voice-dictation";

export function VoiceDictationMinimal() {
  return (
    <div className="w-full max-w-md">
      <VoiceDictation simulate onTranscript={(text) => console.log(text)} />
    </div>
  );
}
```

### Toggle or hold, hotkey and collected notes (full)

Switch modes, use ⌘⇧D, and watch final transcripts collect below.

```tsx
"use client";

import * as React from "react";
import { KbdShortcut } from "@kura-ui/react/kbd-shortcut";
import { VoiceDictation, type VoiceDictationStatus } from "@kura-ui/react/voice-dictation";

export function VoiceDictationFull() {
  const [notes, setNotes] = React.useState<string[]>([]);
  const [status, setStatus] = React.useState<VoiceDictationStatus>("idle");
  const [mode, setMode] = React.useState<"toggle" | "hold">("toggle");
  return (
    <div className="flex w-full max-w-md flex-col gap-4">
      <div className="flex items-center justify-between gap-3">
        <div className="flex rounded-kura-md bg-kura-surface-sunken p-0.5 text-xs shadow-kura-xs">
          {(["toggle", "hold"] as const).map((m) => (
            <button
              key={m}
              type="button"
              aria-pressed={mode === m}
              onClick={() => setMode(m)}
              className="cursor-pointer rounded-kura-sm px-2.5 py-1 text-kura-fg-muted capitalize outline-none transition-colors duration-(--kura-duration-fast) focus-visible:shadow-kura-focus aria-pressed:bg-kura-surface aria-pressed:text-kura-fg aria-pressed:shadow-kura-xs"
            >
              {m}
            </button>
          ))}
        </div>
        <KbdShortcut keys={["mod", "shift", "d"]} label={mode === "hold" ? "Hold" : "Toggle"} />
      </div>
      <VoiceDictation
        simulate="Remind me to send Priya the revised contract after the design review tomorrow."
        mode={mode}
        hotkey={["mod", "shift", "d"]}
        lang="en-US"
        showTranscript
        transcriptPlaceholder="Speak — your words appear here"
        onStatusChange={setStatus}
        onTranscript={(text) => setNotes((n) => [text, ...n])}
      />
      <p className="text-kura-fg-subtle text-xs capitalize" aria-live="polite">
        Status: {status}
      </p>
      <ul aria-label="Dictated notes" className="flex flex-col gap-2">
        {notes.length === 0 && (
          <li className="rounded-kura-lg bg-kura-surface-sunken px-3.5 py-3 text-kura-fg-subtle text-sm">
            Dictated notes appear here.
          </li>
        )}
        {notes.map((note, i) => (
          <li
            key={`${i}-${note}`}
            className="animate-kura-rise-in rounded-kura-lg bg-kura-surface px-3.5 py-3 text-kura-fg text-sm leading-6 shadow-kura-sm"
          >
            {note}
          </li>
        ))}
      </ul>
    </div>
  );
}
```

### Dictating into a composer (composition)

Interim words preview in the placeholder; the final transcript is appended to the composer value.

```tsx
"use client";

import * as React from "react";
import {
  Composer,
  ComposerActions,
  ComposerAttachButton,
  ComposerInput,
  ComposerSubmit,
  ComposerToolbar,
  ComposerTools,
} from "@kura-ui/react/composer";
import { VoiceDictation } from "@kura-ui/react/voice-dictation";

export function VoiceDictationInComposer() {
  const [value, setValue] = React.useState("");
  const [interim, setInterim] = React.useState("");
  return (
    <div className="w-full max-w-xl">
      <Composer value={value} onValueChange={setValue} onSubmit={() => setValue("")}>
        <ComposerInput placeholder={interim || "Type or dictate…"} />
        <ComposerToolbar>
          <ComposerTools>
            <ComposerAttachButton />
          </ComposerTools>
          <ComposerActions>
            <VoiceDictation
              simulate="Find three cafés near the office that open before seven."
              showTranscript={false}
              hotkey={null}
              onInterim={setInterim}
              onStatusChange={(s) => s === "idle" && setInterim("")}
              onTranscript={(text) => setValue((v) => (v ? `${v.trimEnd()} ${text}` : text))}
            />
            <ComposerSubmit />
          </ComposerActions>
        </ComposerToolbar>
      </Composer>
    </div>
  );
}
```

## Dependencies

- npm: `lucide-react`, `motion`
- Kura registry items: `kura-theme`, `audio-waveform`, `kura-keys`, `kura-motion`, `shimmer-text`, `spinner`, `tooltip`, `use-audio-analyser`, `use-hotkey`, `use-media-recorder`, `use-reduced-motion`, `use-speech-recognition`, `utils`
- Related: `composer`, `audio-waveform`, `agent-orb`

---

# Hooks

### useControllableState

One state API for components that support controlled (value/onChange) and uncontrolled (defaultValue) usage.

```ts
import { useControllableState } from "@kura-ui/react/hooks";
useControllableState<T>({ value?: T, defaultValue: T, onChange?: (value: T) => void }): [T, (next: T | ((prev: T) => T)) => void]
```

Returns: [value, setValue] — setValue skips unchanged values and always calls onChange.


```tsx
const [open, setOpen] = useControllableState({ value: props.open, defaultValue: false, onChange: props.onOpenChange });
```

### useReducedMotion

Live, SSR-safe prefers-reduced-motion flag (false on the server).

```ts
import { useReducedMotion } from "@kura-ui/react/hooks";
useReducedMotion(): boolean
```

Returns: true when the user prefers reduced motion.


```tsx
const reduced = useReducedMotion();
<motion.div transition={reduced ? { duration: 0 } : springs.smooth} />
```

### useHotkey

Bind a keyboard shortcut on document (or a target). `mod` = ⌘ on Apple, Ctrl elsewhere. Exact modifier matching.

```ts
import { useHotkey } from "@kura-ui/react/hooks";
useHotkey(keys: readonly KeyName[] | null, handler: (e: KeyboardEvent) => void, options?: { enabled?: boolean; preventDefault?: boolean; allowInInputs?: boolean; target?: EventTarget | null; onKeyUp?: (e: KeyboardEvent) => void }): void
```

Returns: void

- Without a modifier, the shortcut is ignored while typing in inputs unless allowInInputs is true.

```tsx
useHotkey(["mod", "enter"], () => submit());
```

### useIsApplePlatform

Hydration-safe macOS/iOS detection for rendering ⌘ vs Ctrl.

```ts
import { useIsApplePlatform } from "@kura-ui/react/hooks";
useIsApplePlatform(): boolean
```

Returns: true on Apple platforms (false during SSR and the first client render).


```tsx
const apple = useIsApplePlatform();
const label = apple ? "⌘K" : "Ctrl K";
```

### useAudioAnalyser

Web Audio analysis of a mic MediaStream or <audio>/<video> element → level, log-spaced bands and waveform, with a deterministic simulated mode (speech | music | silence) for demos and tests. SSR-safe.

```ts
import { useAudioAnalyser } from "@kura-ui/react/hooks";
useAudioAnalyser({ source?: MediaStream | HTMLMediaElement | null, simulate?: boolean | 'speech' | 'music' | 'silence', bands?: number = 32, fftSize?: number = 1024, smoothing?: number = 0.8, minDecibels?: number = -90, maxDecibels?: number = -10, enabled?: boolean = true }): { status: 'idle' | 'running' | 'simulated' | 'unsupported' | 'error', error: Error | null, read(): AudioFrame, subscribe(listener: (frame: AudioFrame) => void): () => void }
```

Returns: AudioFrame = { level: 0..1, peak: 0..1, bands: Float32Array (0..1), waveform: Float32Array (-1..1), time: ms }

- Frames are not React state. Use subscribe() for canvas/WebGL, or useAudioFrame(analyser, { fps }) for throttled React rendering.
- Arrays in a frame are reused between frames — copy them if you keep them.
- A media element is wired once and kept audible; mic streams are never connected to speakers.

```tsx
const rec = useMediaRecorder();
const analyser = useAudioAnalyser({ source: rec.stream, simulate: !rec.stream && 'silence', bands: 24 });
const { bands } = useAudioFrame(analyser, { fps: 30 });
```

### useAudioFrame

Throttled React-state snapshot of a useAudioAnalyser for simple DOM visualisations.

```ts
import { useAudioFrame } from "@kura-ui/react/hooks";
useAudioFrame(analyser: AudioAnalyser, { fps?: number = 30 }): { level: number; peak: number; bands: number[]; waveform: number[] }
```

Returns: A copied snapshot, updated at most `fps` times per second.


```tsx
const { level } = useAudioFrame(analyser, { fps: 20 });
```

### useMediaRecorder

MediaRecorder wrapper with explicit permission/denied/unsupported states, pause/resume, duration and a final Blob.

```ts
import { useMediaRecorder } from "@kura-ui/react/hooks";
useMediaRecorder({ constraints?: MediaStreamConstraints = { audio: true }, mimeType?: string, timeslice?: number, onDataAvailable?, onStop?, onError? }): { status: 'idle' | 'requesting' | 'recording' | 'paused' | 'stopped' | 'denied' | 'unsupported' | 'error', isSupported, isRecording, stream, blob, mimeType, error, durationMs, start(): Promise<MediaStream | null>, stop(): Promise<Blob | null>, pause(), resume(), reset() }
```

Returns: Controls and state; `stream` is live while recording (feed it to useAudioAnalyser).

- Tracks are stopped on stop/reset/unmount so the mic indicator turns off.

```tsx
const rec = useMediaRecorder({ onStop: (blob) => upload(blob) });
<button onClick={rec.isRecording ? rec.stop : rec.start}>…</button>
```

### useSpeechRecognition

Web Speech API speech-to-text with interim results; reports unsupported (e.g. Firefox) so you can fall back to recording + server transcription.

```ts
import { useSpeechRecognition } from "@kura-ui/react/hooks";
useSpeechRecognition({ lang?: string, continuous?: boolean = true, interimResults?: boolean = true, onResult?, onEnd?, onError? }): { status: 'idle' | 'listening' | 'denied' | 'unsupported' | 'error', isSupported, isListening, transcript, finalTranscript, interimTranscript, error, start(), stop(), abort(), reset() }
```

Returns: Transcripts and controls. `transcript` = final + interim.


```tsx
const speech = useSpeechRecognition({ lang: 'en-US' });
<textarea value={speech.transcript} readOnly />
```

---

# Kura Signal — the Kura UI design language

> **Everything is still until the model speaks.**
> Surfaces are quiet paper and ink. Motion and colour are a _signal_: they appear only where an
> agent is thinking, listening, streaming or asking for something.

Kura (蔵) is a storehouse — a calm, well-made place where valuable things are kept. The
components are instruments for working with models: precise, warm, legible, a little tactile,
never loud. This document is the contract every component follows. It is distilled from the
craft of people we admire (Emil Kowalski's work on Sonner/Vaul and animation, Rauno Freiberg's
"Invisible Details of Interaction Design", Paco Coursey's cmdk, Jhey Tompkins' playful CSS,
Vercel Geist, Linear, Raycast, Family) and from the AI-interface wave (AI Elements, ElevenLabs UI,
prompt-kit, assistant-ui). We take principles, not looks.

---

## 1. Principles

1. **Quiet by default, alive on signal.** Neutral surfaces, one accent. The accent (jade
   "signal") means _the machine is doing something_: streaming, listening, running a tool,
   awaiting approval. If nothing is happening, nothing glows.
2. **Responsive before decorative.** Every interaction acknowledges input within one frame
   (press scale, hover tint, focus ring). Decoration is optional; feedback is not.
3. **Motion explains, never performs.** Animate to show where something came from, what changed,
   or that work is in progress. Never animate to fill time.
4. **Interruptible everything.** A user can reverse any gesture or state mid-flight. Use springs
   (they keep velocity) or CSS transitions (they retarget) — never keyframes for state toggles.
5. **Text is the interface.** Model output is text. Typography, rhythm and contrast matter more
   than chrome.
6. **Agents read our components too.** Every component ships a manifest (`*.meta.ts`) so an agent
   can choose it, configure it and compose it without guessing. Clear names, explicit states,
   data attributes for every part (`data-slot`, `data-state`).

---

## 2. Color

All colors are OKLCH CSS variables defined in `packages/react/src/styles/kura.css` and exposed to
Tailwind as `*-kura-*` utilities. **Components never hard-code colors and never use `dark:`** —
tokens flip under `.dark` or `[data-theme="dark"]`.

### Neutral scale — warm "paper" gray (hue 85, chroma ≤ 0.008)

| Step      | Use                       | Light                   | Dark                    |
| --------- | ------------------------- | ----------------------- | ----------------------- |
| `gray-1`  | app canvas                | `oklch(0.993 0.002 85)` | `oklch(0.155 0.004 85)` |
| `gray-2`  | subtle / sunken bg        | `oklch(0.982 0.003 85)` | `oklch(0.185 0.004 85)` |
| `gray-3`  | UI element bg             | `oklch(0.962 0.004 85)` | `oklch(0.215 0.005 85)` |
| `gray-4`  | hovered element bg        | `oklch(0.942 0.005 85)` | `oklch(0.24 0.005 85)`  |
| `gray-5`  | active element bg         | `oklch(0.92 0.005 85)`  | `oklch(0.265 0.006 85)` |
| `gray-6`  | subtle borders            | `oklch(0.895 0.006 85)` | `oklch(0.295 0.006 85)` |
| `gray-7`  | borders                   | `oklch(0.86 0.006 85)`  | `oklch(0.345 0.007 85)` |
| `gray-8`  | strong borders, focus     | `oklch(0.8 0.007 85)`   | `oklch(0.42 0.008 85)`  |
| `gray-9`  | solid                     | `oklch(0.64 0.008 85)`  | `oklch(0.56 0.008 85)`  |
| `gray-10` | placeholder / subtle text | `oklch(0.58 0.008 85)`  | `oklch(0.64 0.008 85)`  |
| `gray-11` | muted text (≥ 4.5:1)      | `oklch(0.47 0.008 85)`  | `oklch(0.76 0.007 85)`  |
| `gray-12` | primary text, ink         | `oklch(0.205 0.006 85)` | `oklch(0.955 0.004 85)` |

### Semantic tokens (use these, not the scale)

| Utility                                                                                        | Meaning                                                   |
| ---------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| `bg-kura-canvas`                                                                               | page background                                           |
| `bg-kura-surface` / `-raised` / `-sunken`                                                      | cards, raised panels, wells and inputs                    |
| `bg-kura-overlay`                                                                              | translucent popovers/menus (pair with `backdrop-blur-xl`) |
| `bg-kura-hover` / `bg-kura-active`                                                             | translucent hover/pressed tints (work on any surface)     |
| `text-kura-fg` / `-fg-muted` / `-fg-subtle` / `-fg-inverted`                                   | text hierarchy                                            |
| `border-kura-border` / `-border-subtle` / `-border-strong`                                     | translucent hairlines                                     |
| `bg-kura-ink` / `-ink-hover`                                                                   | primary (ink) buttons                                     |
| `bg-kura-accent` / `-accent-hover` / `-accent-fg` / `-accent-subtle` / `text-kura-accent-text` | the signal                                                |
| `kura-danger*`, `kura-success*`, `kura-warning*`                                               | status only — never decoration                            |
| `kura-ring`                                                                                    | focus ring color                                          |

### The one accent — "signal" (jade, hue ~172)

Light `oklch(0.55 0.115 172)`, dark `oklch(0.78 0.13 170)`. Rules:

- At most **one** accent-filled element per view (e.g. the "Run agent" button or the live orb).
- Use `accent-subtle` + `accent-text` for small live states (a running step, a listening pill).
- The primary call-to-action is **ink**, not accent. Accent is for AI-specific actions and states.
- No purple-to-pink "AI gradients", no sparkles as decoration (see Anti-patterns).

---

## 3. Typography

- **Sans:** Geist (via `geist`/`next/font` or `@fontsource-variable/geist`), falling back to
  Inter, `ui-sans-serif`, `system-ui`. Token: `font-kura-sans`.
- **Mono:** Geist Mono → `ui-monospace`, SF Mono, JetBrains Mono, Menlo. Token: `font-kura-mono`.
  Use mono for code, token counts, IDs, timings, keyboard-like data.
- Kura reads `--font-geist-sans` / `--font-geist-mono` if your app defines them (next/font does).
- Scale (px): 11 · 12 · 13 · 14 (UI default) · 15 · 16 (reading) · 20 · 24 · 32 · 48.
- Use `tabular-nums` for anything that counts or ticks (timers, tokens, costs).
- Body copy line-height 1.6; UI labels 1.25–1.4; display tight (`tracking-tight`, 1.05–1.15).
- Headings use weight 500–600, never 700+ in UI. Contrast comes from size and color, not weight.
- Streaming text never reflows previous lines; reserve height or append only.

---

## 4. Shape: radii, borders, shadows

**Radii:** `rounded-kura-xs` 4 · `sm` 6 · `md` 8 · `lg` 12 · `xl` 16 · `2xl` 20 · full for pills.
Nested corners are concentric: `inner = outer − padding` (a 16px card with 4px padding holds
12px children).

**Hairline borders.** Borders are translucent (`oklch(ink / 0.07–0.2)`) so they work on any
surface. We prefer **shadow-rings** (`0 0 0 1px var(--kura-border)`) over `border` so elements do
not shift by a pixel when the border appears, and so rings composite with elevation.

**Layered shadows** — a ring plus tight, low-opacity ambient layers:

| Token               | Use                              |
| ------------------- | -------------------------------- |
| `shadow-kura-xs`    | buttons, keycaps, chips          |
| `shadow-kura-sm`    | cards, inputs, composers at rest |
| `shadow-kura-md`    | raised cards, tooltips, toasts   |
| `shadow-kura-lg`    | popovers, menus, dialogs         |
| `shadow-kura-focus` | the focus ring (see §7)          |

In dark mode shadows carry less meaning; elevation comes from a lighter surface plus a 1px inner
top highlight (`inset 0 1px 0 oklch(1 0 0 / 0.04)`), built into the dark tokens.

---

## 5. Motion

### Durations (CSS `--kura-duration-*`, JS `durations.*` in seconds)

| Token     | ms  | Use                                      |
| --------- | --- | ---------------------------------------- |
| `instant` | 90  | exits, hover tints, key presses          |
| `fast`    | 150 | tooltips, small popovers, press feedback |
| `base`    | 220 | dropdowns, toggles, list insertions      |
| `slow`    | 320 | panels, larger reveals                   |
| `slower`  | 480 | page-level, hero, drawers                |

UI motion stays under 300ms. Anything triggered dozens of times a day (menus, command palette)
should be _fast_ or not animate at all.

### Easing (CSS `ease-kura-*`, JS `easings.*`)

- **`out` — `cubic-bezier(0.23, 1, 0.32, 1)`**: the default. Enters and anything the user
  triggers. Fast start = feels responsive.
- **`in-out` — `cubic-bezier(0.77, 0, 0.175, 1)`**: on-screen movement from A to B.
- **`in` — `cubic-bezier(0.55, 0, 1, 0.45)`**: exits only, and short.
- **`spring` — a CSS `linear()` spring** with ~0.6% overshoot for CSS-only "settle".
- Never `linear` except for continuous loops (spinners, shimmer, marquee). Never `ease-in` on enter.

### Springs (motion/react — `import { springs } from "@kura-ui/react/utils"`)

| Preset   | Config                                                 | Use                                              |
| -------- | ------------------------------------------------------ | ------------------------------------------------ |
| `snappy` | `{ type: "spring", visualDuration: 0.2, bounce: 0.1 }` | presses, toggles, small flips                    |
| `smooth` | `{ visualDuration: 0.35, bounce: 0 }`                  | layout, panels, popovers (default)               |
| `gentle` | `{ visualDuration: 0.5, bounce: 0.05 }`                | sheets, drawers, hero                            |
| `bouncy` | `{ visualDuration: 0.4, bounce: 0.25 }`                | delight moments, orbs, success ticks — sparingly |

### Rules

- **Origin-aware.** Popovers and tooltips scale from their trigger
  (`origin-(--radix-popover-content-transform-origin)`), from `0.96`, never from `0`.
- **Enter slower than exit.** Exits are ~60% of the enter duration.
- **Interruptible.** Use transitions/springs for state; keyframes only for one-shot enters and loops.
- **Skip repeat animations.** Moving between tooltips is instant (`data-[state=instant-open]:animate-none`).
- **Press feedback:** `active:scale-[0.97]` on buttons; keys travel 1px.
- **Blur for state swaps.** When swapping text/icons in place, cross-fade with 2px blur rather
  than sliding.
- **Animate `transform`, `opacity`, `filter`, `clip-path`.** Never width/height/top/left for
  continuous motion. Use `layout` animations from motion for size changes.
- **Stagger** list reveals 30–50ms per item, capped at ~8 items.
- **Streaming:** append tokens without animating each one; animate the _caret_ and the end-of-stream
  settle instead.

### Reduced motion (`prefers-reduced-motion: reduce`)

Not "no motion" — _no travel_. Keep opacity fades (they carry meaning), remove translation,
scale, blur, parallax, and continuous loops.

- CSS tokens do it automatically: `--kura-pop-scale: 1`, `--kura-pop-y: 0`, `--kura-rise-*: 0`.
- Tailwind: `motion-reduce:animate-none`, `motion-reduce:scale-100`, etc.
- JS: `useReducedMotion()` from `@kura-ui/react/hooks`; pass `reducedTransition` or a fade.
- Shaders render one still frame; audio visualisers show a static level meter.
- Every component test covers reduced motion.

---

## 6. Density & layout

- Base unit 4px. Control heights: 24 (xs) · 28 (sm) · 32 (md, default) · 40 (lg).
- Hit targets ≥ 24×24 on desktop; ≥ 44×44 on touch (`pointer-coarse:` variants).
- Default UI font 14px, 13px in dense toolbars, 15–16px for conversation text.
- Content measure for model output: 60–75ch.
- Use `gap`, not margins, inside components. Components never set outer margins.

---

## 7. Focus & states

- Focus ring: `focus-visible:shadow-kura-focus` = 1px canvas gap + 2px signal ring at 55%.
  Only on `:focus-visible`, never on mouse click. Never `outline-none` without a replacement.
- States are exposed as data attributes for styling and for agents: `data-state="open|closed"`,
  `data-active`, `data-pressed`, `data-status="idle|running|done|error"`.
- Disabled = 50% opacity + `cursor-not-allowed` + the native `disabled` attribute.
- Loading keeps the element's size (no layout shift) and sets `aria-busy`.

---

## 8. Sound & haptics

- **Off by default.** Sound is opt-in per app (`sound` prop or context), never per component.
- When enabled: very short (< 120ms), soft, low-volume cues only for *events the user did not
  directly cause*: an agent finished, approval needed, recording started/stopped.
- Haptics (`navigator.vibrate(8)`) only on touch devices, only for confirmations and
  start/stop of recording. Never on hover, never repeated.
- Respect `prefers-reduced-motion` as a proxy for "reduce sensory load" — no sounds/haptics then.

---

## 9. Accessibility baseline

- WCAG 2.2 AA contrast for text (`fg-muted` ≥ 4.5:1 on canvas in both themes).
- Every interactive element is keyboard reachable, has a visible focus ring and an accessible
  name. Icon-only buttons require `label`.
- Live AI output: use `role="status"`/`aria-live="polite"` for progress; `role="log"` for
  conversation; never announce every streamed token — announce the completed message.
- Decorative visuals (`ShaderCanvas`, orbs, gradients) are `aria-hidden`.
- Audio/voice components expose a text equivalent of their state ("Listening", "Muted").

---

## 10. Anti-patterns (we do not ship these)

- Purple→pink "AI" gradients, sparkle ✨ icons as decoration, glowing everything.
- Animating on every keystroke or token; bouncing UI that the user triggers 100× a day.
- `ease-in` enters, `linear` UI transitions, durations over 400ms for UI state.
- Scale from 0, transform-origin center on anchored popovers.
- Hard-coded hex colors, `dark:` overrides in components, opaque borders that double up.
- Spinners for model "thinking" (use shimmer-text / thinking-indicator — it's thought, not network).
- Layout shift when content streams in or a button enters a loading state.
- Tooltips with essential info or interactive content; icon buttons without labels.
- Fake progress bars, fake typing delays, dark patterns around approval/consent.
- Components that set outer margins, fixed widths, or global styles.