, <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, Pencil } 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> } /> <Button size="xs" variant="ghost" className="self-end" disabled={busy} onClick={() => { setRun((r) => r + 1); setVersion(run + 2); }} > <Pencil /> Ask for an edit </Button> </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 blue accent (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} 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` --- # Browser Session > A computer/browser-use session made legible: tidy browser frame, the page, the agent's cursor with click ripple and target box, and a step log with take-over. - **Slug:** `browser-session` · **Category:** workspace · **Status:** experimental - **Import:** `import { BrowserHighlight, BrowserPoint, BrowserSession, BrowserStep, BrowserStepKind } from "@kura-ui/react/browser-session";` - **Docs:** https://kuro.abstergo.fyi/components/browser-session - **Registry item:** https://kuro.abstergo.fyi/r/browser-session.json - **Tags:** agent, browser, computer-use, browser-use, operator, cursor, screenshot, takeover ## Install ```bash # shadcn registry (copies source into your project) npx shadcn@latest add https://kuro.abstergo.fyi/r/browser-session.json # Kura CLI (same, plus dependency resolution and --json output) npx @kura-ui/cli add browser-session # npm package npm install @kura-ui/react ``` ## When to use - Show what a browser-use or computer-use agent is doing on a web page (Operator, Claude computer use, Browserbase, Playwright-driven agents). - Stream screenshots of a remote browser (`src`) with the agent's next action drawn on top (`cursor`, `highlight`). - Replay a recorded browser run step by step with the log of navigate / click / type / scroll / extract actions. - Hand control to the human when the agent hits a login, 2FA or CAPTCHA (`status="paused"` + `onResume`), or let them take over (`onTakeOver`). ## When not to use - Terminal or shell output from the agent — use terminal. - Code edits made by the agent — use diff-view or file-changes. - A plan or todo list of the whole run — use task-list. - A static rendered artifact (HTML preview, document) — use artifact-card. ## Props | Prop | Type | Default | Required | Description | | --- | --- | --- | --- | --- | | `url` | `string` | — | yes | Page URL in the address bar. The host is emphasised, the path muted; https shows a lock. | | `title` | `string` | — | no | Page title next to the address bar (hidden in narrow containers). | | `children` | `React.ReactNode` | — | no | Viewport content: a live page, or a mock rendered as markup. | | `src` | `string` | — | no | A screenshot URL to show instead of children (e.g. the latest frame from a remote browser). | | `alt` | `string` | — | no | Alt text for `src`. Default “Screenshot of {url}”. | | `viewport` | `{ width: number; height: number }` | — | no | Design size of the page in CSS px (e.g. the agent's 1280×800 screen). Children render at this size and scale to fit the frame, so % coordinates stay exact at any width. Omit to let children flow at the frame's width. | | `aspectRatio` | `number` | `16 / 10` | no | Viewport aspect ratio when `viewport` is not given. | | `scrollTop` | `number` | `0` | no | Vertical page scroll in viewport px; eases on change (use for scroll steps). | | `cursor` | `BrowserPoint \| null` | — | no | The agent's cursor { x, y } in % of the viewport. Glides to new positions. | | `cursorLabel` | `string` | — | no | Name tag on the cursor, e.g. the agent's name. | | `clickKey` | `string \| number` | — | no | Change it to play a click ripple at the cursor. Default: the active step's id when that step is a click. | | `highlight` | `BrowserHighlight \| null` | — | no | Box around the target element: { x, y, width, height } in % plus an optional `label` tag (e.g. `button "Create pull request"`). | | `steps` | `readonly BrowserStep[]` | — | no | The action log. BrowserStep = { id, kind: "navigate" \| "click" \| "type" \| "scroll" \| "extract", label, status: AgentStatus, detail? (mono: URL, selector, typed text) }. Omit to hide the log. | | `activeStep` | `string` | — | no | Id of the step being executed. Default: the first running step. | | `status` | `"browsing" \| "paused" \| "done" \| "failed"` | `"browsing"` | no | browsing = “Agent is browsing” (blue, shimmer); paused = “Paused for you” (amber, the viewport gets an amber edge); done; failed. | | `statusText` | `React.ReactNode` | — | no | Secondary text after the status, e.g. “Enter the 2FA code, then hand back”. | | `startedAt` | `Date \| number` | — | no | Session start (wall clock) for the elapsed clock; ticks while browsing. | | `loading` | `boolean` | — | no | Show the loading bar under the address bar. Default: true while the active step is a running navigate. | | `actions` | `React.ReactNode` | — | no | Extra controls in the status line (e.g. open in new tab, replay). | | `onTakeOver` | `() => void` | — | no | Shows a “Take over” button while browsing. | | `onResume` | `() => void` | — | no | Shows a “Resume agent” button while paused. | | `layout` | `"auto" \| "side" \| "stacked"` | `"auto"` | no | Step log beside the browser (side), below it (stacked), or beside only when the container is ≥ 48rem (auto). | Native attributes of the root element, `className` and `ref` are passed through. ## Anatomy - **BrowserSession** (`data-slot="browser-session"`) — Root panel; `data-status`, `data-layout`; container-query context; polite status region. - **Header** (`data-slot="browser-session-header"`) — Status line: glyph, “Agent is browsing” / “Paused for you”, statusText, done/total, elapsed, actions, Take over / Resume. - **Elapsed** (`data-slot="browser-session-elapsed"`) — Mono clock from startedAt. - **Browser** (`data-slot="browser-session-browser"`) — Column with the chrome and the viewport. - **Chrome** (`data-slot="browser-session-chrome"`) — Title (favicon letter + text) and the address bar. - **Address** (`data-slot="browser-session-address"`) — role="group" “Address”: lock, host, muted path, in mono. - **Loading** (`data-slot="browser-session-loading"`) — 2px accent sweep under the chrome while a page loads. - **Viewport** (`data-slot="browser-session-viewport"`) — Fixed-aspect frame (no layout shift); amber inner edge while paused. - **Page** (`data-slot="browser-session-page"`) — Holds children/src; scaled to fit when `viewport` is set; translated by scrollTop. - **Overlay** (`data-slot="browser-session-overlay"`) — aria-hidden layer for the highlight, ripple and cursor. - **Highlight** (`data-slot="browser-session-highlight"`) — Accent box + mono tag around the target; eases between targets. - **Cursor** (`data-slot="browser-session-cursor"`) — Pointer arrow with an optional accent name tag; glides between points. - **Ripple** (`data-slot="browser-session-ripple"`) — Accent ring that expands and fades after the cursor arrives. - **Log** (`data-slot="browser-session-log"`) — Scrollable step log; keeps the active step in view. - **Step** (`data-slot="browser-session-step"`) — <li> with `data-kind`, `data-status`, `data-active`; aria-current="step" on the active one. ## Accessibility - The overlay (cursor, ripple, highlight) is decorative and aria-hidden; what the agent is doing is carried by the step log and the status line. - The step log is an <ol> labelled “Browser actions”; each step speaks its status after the label, and the active one has aria-current="step". - A polite status region announces the active step's label (when it is a string), “Paused for you” / your statusText, “Session ended” or “Session failed” — never the ticking clock. - The address bar is a labelled group; the lock icon is labelled “Secure connection”. With `src`, the image gets alt text (default “Screenshot of {url}”). - Take over / Resume agent are real buttons with visible focus. Paused state is signalled by text and glyph, not only the amber edge. - Reduced motion: The cursor and highlight jump instead of gliding (the highlight still fades), the click ripple is skipped, page scroll is instant, the loading sweep becomes a static bar and the shimmer stops. | Keys | Action | | --- | --- | | Tab | Moves to the status-line actions (Take over / Resume agent) and any controls inside the page. | ## Notes for agents - Coordinates are percentages of the viewport. If your agent reports pixels on a W×H screen, pass `viewport={{ width: W, height: H }}` and use x = px / W * 100. - For remote browsers pass the latest screenshot as `src` and keep `viewport` equal to the screenshot size; draw the *next* action with `cursor` + `highlight`. - Change `clickKey` (e.g. an action counter) to replay the ripple; repeated clicks on the same step otherwise only ripple once. - Set `status="paused"` whenever the agent needs the human (login, 2FA, CAPTCHA, payment) and say why in `statusText`. - Map the agent's actions to the five kinds; put the URL, selector or typed text in `detail` (mono). ## Examples ### A page with the agent's cursor (minimal) A mock PR page at a fixed 800×500 design size, the cursor and a target box. ```tsx import { Check, GitPullRequest } from "lucide-react"; import { BrowserSession } from "@kura-ui/react/browser-session"; const W = 800; const H = 500; const at = (x: number, y: number) => ({ x: (x / W) * 100, y: (y / H) * 100 }); const box = (x: number, y: number, w: number, h: number, label?: string) => ({ x: (x / W) * 100, y: (y / H) * 100, width: (w / W) * 100, height: (h / H) * 100, label, }); function PullRequestPage() { return ( <div className="h-[500px] bg-kura-surface font-kura-sans text-kura-fg"> <SiteBar /> <div className="px-8 pt-6"> <h1 data-target="pr-h1" className="font-semibold text-[20px] leading-7 tracking-[-0.015em]"> {PR_TITLE} <span className="font-normal text-kura-fg-subtle">#482</span> </h1> <div className="mt-2 flex items-center gap-2 text-[13px] text-kura-fg-muted"> <span className="flex items-center gap-1 rounded-full bg-kura-success/15 px-2 py-0.5 font-medium text-[12px] text-kura-success-text"> <GitPullRequest className="size-3" strokeWidth={2} /> Open </span> <span> <span className="font-medium text-kura-fg">kura</span> wants to merge 4 commits into{" "} <span className="font-kura-mono text-[12px]">main</span> from{" "} <span className="font-kura-mono text-[12px]">kura/auth-client</span> </span> </div> <div className="mt-4 flex gap-5 border-kura-border-subtle border-b text-[13px] text-kura-fg-muted"> <span className="-mb-px border-kura-fg border-b-2 pb-2 font-medium text-kura-fg"> Conversation </span> <span>Commits 4</span> <span>Checks 3</span> <span>Files changed 6</span> </div> <div className="mt-4 rounded-[10px] p-4 text-[13px] text-kura-fg-muted leading-5 shadow-kura-xs"> {PR_BODY} </div> <div className="mt-3 flex flex-col rounded-[10px] text-[13px] shadow-kura-xs"> <div className="flex h-10 items-center gap-2 border-kura-border-subtle border-b px-4 font-medium"> <Check className="size-4 text-kura-success" strokeWidth={2.25} /> All checks have passed </div> {[ ["test", "142 passed · 41s"], ["typecheck", "0 errors · 18s"], ["lint", "clean · 6s"], ].map(([name, meta]) => ( <div key={name} className="flex h-9 items-center gap-2 px-4"> <Check className="size-3.5 text-kura-success" strokeWidth={2.25} /> <span className="font-kura-mono text-[12.5px]">{name}</span> <span className="ml-auto font-kura-mono text-[12px] text-kura-fg-subtle">{meta}</span> </div> ))} </div> </div> </div> ); } const PR_TITLE = "Migrate session API to @acme/auth client"; const PR_BODY = "Replaces fetchUser() and the legacy /api/session REST calls with createAuthClient(). Refreshes expired sessions with the rotated token."; function SiteBar() { return ( <div className="flex h-12 items-center gap-3 border-kura-border-subtle border-b px-8 text-[14px]"> <span className="size-5 rounded-[5px] bg-kura-fg" /> <span className="text-kura-fg-muted">acme</span> <span className="text-kura-fg-subtle">/</span> <span className="font-semibold">web</span> <span className="ml-auto flex items-center gap-5 text-[13px] text-kura-fg-muted"> <span>Code</span> <span className="font-medium text-kura-fg">Pull requests</span> <span>Actions</span> <span className="size-6 rounded-full bg-kura-gray-5" /> </span> </div> ); } export function BrowserSessionMinimal() { return ( <BrowserSession className="w-full max-w-xl" url="https://github.com/acme/web/pull/482" title="Migrate session API · acme/web" viewport={{ width: W, height: H }} cursor={at(468, 94)} highlight={box(24, 66, 478, 40, "h1")} > <PullRequestPage /> </BrowserSession> ); } ``` ### Opening the pull request (full) Kura opens the compare view, types the title and description, clicks “Create pull request” and reads the PR number. The cursor glides, clicks ripple, the log advances and the session settles. ```tsx "use client"; import { Check, GitBranch, GitPullRequest, RotateCcw } from "lucide-react"; import * as React from "react"; import { IconButton } from "@kura-ui/react/icon-button"; import { BrowserSession, type BrowserStep } from "@kura-ui/react/browser-session"; const W = 800; const H = 500; const PR_TITLE = "Migrate session API to @acme/auth client"; const PR_BODY = "Replaces fetchUser() and the legacy /api/session REST calls with createAuthClient(). Refreshes expired sessions with the rotated token."; function ComparePage({ title, body, focus, }: { title: string; body: string; focus: "title" | "body" | null; }) { return ( <div className="h-[500px] bg-kura-surface font-kura-sans text-kura-fg"> <SiteBar /> <div className="px-8 pt-6"> <h1 className="font-semibold text-[20px] leading-7 tracking-[-0.015em]"> Open a pull request </h1> <p className="mt-1 text-[13px] text-kura-fg-muted leading-5"> Create a new pull request by comparing changes across two branches. </p> <div className="mt-4 flex h-10 items-center gap-2 rounded-[8px] bg-kura-surface-sunken px-3 text-[12.5px]"> <GitBranch className="size-3.5 text-kura-fg-subtle" strokeWidth={1.75} /> <span className="rounded-[5px] bg-kura-surface px-1.5 py-0.5 font-kura-mono shadow-kura-xs"> base: main </span> <span className="text-kura-fg-subtle">←</span> <span className="rounded-[5px] bg-kura-surface px-1.5 py-0.5 font-kura-mono shadow-kura-xs"> compare: kura/auth-client </span> <span className="ml-auto flex items-center gap-1 font-medium text-kura-success-text"> <Check className="size-3.5" strokeWidth={2.25} /> Able to merge </span> </div> <div className="mt-4 flex flex-col gap-1.5 rounded-[10px] p-4 shadow-kura-xs"> <span className="font-medium text-[12.5px] leading-[18px]">Title</span> <Field value={title} focused={focus === "title"} /> <span className="mt-1.5 font-medium text-[12.5px] leading-[18px]">Description</span> <Field value={body} focused={focus === "body"} tall /> <div className="mt-1.5 flex h-8 items-center justify-between"> <span className="text-[12px] text-kura-fg-subtle">Markdown is supported</span> <span data-target="submit" className="flex h-8 w-[160px] items-center justify-center rounded-[7px] bg-kura-ink font-medium text-[13px] text-kura-fg-inverted" > Create pull request </span> </div> </div> <p className="mt-3 font-kura-mono text-[12px] text-kura-fg-subtle"> 4 commits · 6 files changed · +142 −38 </p> </div> </div> ); } function PullRequestPage() { return ( <div className="h-[500px] bg-kura-surface font-kura-sans text-kura-fg"> <SiteBar /> <div className="px-8 pt-6"> <h1 data-target="pr-h1" className="font-semibold text-[20px] leading-7 tracking-[-0.015em]"> {PR_TITLE} <span className="font-normal text-kura-fg-subtle">#482</span> </h1> <div className="mt-2 flex items-center gap-2 text-[13px] text-kura-fg-muted"> <span className="flex items-center gap-1 rounded-full bg-kura-success/15 px-2 py-0.5 font-medium text-[12px] text-kura-success-text"> <GitPullRequest className="size-3" strokeWidth={2} /> Open </span> <span> <span className="font-medium text-kura-fg">kura</span> wants to merge 4 commits into{" "} <span className="font-kura-mono text-[12px]">main</span> from{" "} <span className="font-kura-mono text-[12px]">kura/auth-client</span> </span> </div> <div className="mt-4 flex gap-5 border-kura-border-subtle border-b text-[13px] text-kura-fg-muted"> <span className="-mb-px border-kura-fg border-b-2 pb-2 font-medium text-kura-fg"> Conversation </span> <span>Commits 4</span> <span>Checks 3</span> <span>Files changed 6</span> </div> <div className="mt-4 rounded-[10px] p-4 text-[13px] text-kura-fg-muted leading-5 shadow-kura-xs"> {PR_BODY} </div> <div className="mt-3 flex flex-col rounded-[10px] text-[13px] shadow-kura-xs"> <div className="flex h-10 items-center gap-2 border-kura-border-subtle border-b px-4 font-medium"> <Check className="size-4 text-kura-success" strokeWidth={2.25} /> All checks have passed </div> {[ ["test", "142 passed · 41s"], ["typecheck", "0 errors · 18s"], ["lint", "clean · 6s"], ].map(([name, meta]) => ( <div key={name} className="flex h-9 items-center gap-2 px-4"> <Check className="size-3.5 text-kura-success" strokeWidth={2.25} /> <span className="font-kura-mono text-[12.5px]">{name}</span> <span className="ml-auto font-kura-mono text-[12px] text-kura-fg-subtle">{meta}</span> </div> ))} </div> </div> </div> ); } const COMPARE_URL = "https://github.com/acme/web/compare/main...kura/auth-client"; const PR_URL = "https://github.com/acme/web/pull/482"; const STEPS: Omit<BrowserStep, "status">[] = [ { id: "open", kind: "navigate", label: "Open the compare view", detail: COMPARE_URL.slice(8) }, { id: "focus", kind: "click", label: "Focus the title field", detail: "input#pr-title" }, { id: "title", kind: "type", label: "Type the PR title", detail: `“${PR_TITLE}”` }, { id: "body", kind: "type", label: "Write the description", detail: `“${PR_BODY.slice(0, 48)}…”`, }, { id: "submit", kind: "click", label: "Click “Create pull request”", detail: "button[type=submit]", }, { id: "read", kind: "extract", label: "Read the PR number", detail: "#482 · Open" }, ]; const TARGETS = { open: { cursor: at(400, 300), highlight: null }, focus: { cursor: at(140, 256), highlight: box(48, 236, 704, 36, "input#pr-title") }, title: { cursor: at(140, 256), highlight: box(48, 236, 704, 36, "input#pr-title") }, body: { cursor: at(160, 330), highlight: box(48, 308, 704, 96, "textarea#pr-body") }, submit: { cursor: at(690, 434), highlight: box(592, 416, 160, 32, 'button "Create pull request"'), }, read: { cursor: at(468, 94), highlight: box(24, 66, 478, 40, "h1 · #482") }, } as const; const at = (x: number, y: number) => ({ x: (x / W) * 100, y: (y / H) * 100 }); const box = (x: number, y: number, w: number, h: number, label?: string) => ({ x: (x / W) * 100, y: (y / H) * 100, width: (w / W) * 100, height: (h / H) * 100, label, }); function SiteBar() { return ( <div className="flex h-12 items-center gap-3 border-kura-border-subtle border-b px-8 text-[14px]"> <span className="size-5 rounded-[5px] bg-kura-fg" /> <span className="text-kura-fg-muted">acme</span> <span className="text-kura-fg-subtle">/</span> <span className="font-semibold">web</span> <span className="ml-auto flex items-center gap-5 text-[13px] text-kura-fg-muted"> <span>Code</span> <span className="font-medium text-kura-fg">Pull requests</span> <span>Actions</span> <span className="size-6 rounded-full bg-kura-gray-5" /> </span> </div> ); } function Field({ value, focused, tall }: { value: string; focused: boolean; tall?: boolean }) { return ( <div data-target={tall ? "body" : "title"} className={ tall ? "h-24 rounded-[7px] bg-kura-surface px-3 py-2 text-[13px] leading-5" : "flex h-9 items-center rounded-[7px] bg-kura-surface px-3 text-[13.5px]" } style={{ boxShadow: focused ? "0 0 0 1px var(--kura-accent), 0 0 0 3px var(--kura-ring)" : "0 0 0 1px var(--kura-border-strong)", }} > <span>{value}</span> {focused && ( <span className="ml-px inline-block h-4 w-px translate-y-[3px] animate-kura-pulse bg-kura-fg" /> )} {!value && !focused && ( <span className="text-kura-fg-subtle">{tall ? "Add a description" : "Title"}</span> )} </div> ); } export function BrowserSessionFull() { const [step, setStep] = React.useState(0); const [typed, setTyped] = React.useState({ title: 0, body: 0 }); const [clicks, setClicks] = React.useState(0); const [run, setRun] = React.useState(0); const [startedAt, setStartedAt] = React.useState<number>(); // biome-ignore lint/correctness/useExhaustiveDependencies: `run` replays the session React.useEffect(() => { setStep(0); setTyped({ title: 0, body: 0 }); setStartedAt(Date.now() - 6 * 60_000 - 12_000); const timers: ReturnType<typeof setTimeout>[] = []; const later = (ms: number, fn: () => void) => timers.push(setTimeout(fn, ms)); const type = (from: number, ms: number, key: "title" | "body", total: number) => { const n = 24; for (let i = 1; i <= n; i++) later(from + (ms / n) * i, () => setTyped((t) => ({ ...t, [key]: Math.round((total * i) / n) })), ); }; later(1300, () => setStep(1)); later(2300, () => setStep(2)); type(2400, 1500, "title", PR_TITLE.length); later(4100, () => { setStep(3); setClicks((c) => c + 1); }); type(4600, 1600, "body", PR_BODY.length); later(6500, () => setStep(4)); later(7700, () => setStep(5)); later(9200, () => setStep(6)); return () => timers.forEach(clearTimeout); }, [run]); const created = step >= 5; const current = STEPS[step]; const target = current ? TARGETS[current.id as keyof typeof TARGETS] : TARGETS.read; const steps: BrowserStep[] = STEPS.map((s, i) => ({ ...s, status: i < step ? "done" : i === step ? "running" : "queued", })); return ( <BrowserSession className="w-full max-w-4xl" url={created ? PR_URL : COMPARE_URL} title={created ? "Migrate session API · acme/web" : "Open a pull request · acme/web"} viewport={{ width: W, height: H }} status={step >= STEPS.length ? "done" : "browsing"} startedAt={startedAt} steps={steps} cursor={target.cursor} cursorLabel="Kura" clickKey={`${run}-${clicks}-${current?.kind === "click" ? current.id : ""}`} highlight={step >= STEPS.length ? null : target.highlight} onTakeOver={() => {}} statusText={step >= STEPS.length ? "acme/web#482 opened" : undefined} actions={ step >= STEPS.length && ( <IconButton label="Replay" icon={<RotateCcw />} variant="ghost" size="xs" className="animate-kura-fade-in" onClick={() => setRun((r) => r + 1)} /> ) } > <div className={step === 0 ? "opacity-40 transition-opacity" : "transition-opacity"}> {created ? ( <PullRequestPage /> ) : ( <ComparePage title={PR_TITLE.slice(0, typed.title)} body={PR_BODY.slice(0, typed.body)} focus={step === 1 || step === 2 ? "title" : step === 3 ? "body" : null} /> )} </div> </BrowserSession> ); } ``` ### Paused for you (state) A 2FA prompt only the human can answer: amber edge, “Resume agent”. ```tsx "use client"; import { Check } from "lucide-react"; import * as React from "react"; import { BrowserSession } from "@kura-ui/react/browser-session"; const W = 800; const H = 500; const at = (x: number, y: number) => ({ x: (x / W) * 100, y: (y / H) * 100 }); const box = (x: number, y: number, w: number, h: number, label?: string) => ({ x: (x / W) * 100, y: (y / H) * 100, width: (w / W) * 100, height: (h / H) * 100, label, }); function TwoFactorPage() { return ( <div className="flex h-[500px] flex-col items-center bg-kura-surface-sunken pt-16 font-kura-sans text-kura-fg"> <div className="flex w-[360px] flex-col items-center gap-1 rounded-[14px] bg-kura-surface px-8 py-7 shadow-kura-sm"> <span className="mb-3 size-8 rounded-[8px] bg-kura-fg" /> <h1 className="font-semibold text-[17px] tracking-[-0.01em]">Two-factor authentication</h1> <p className="text-center text-[13px] text-kura-fg-muted leading-5"> Enter the 6-digit code from your authenticator app to continue to Acme Cloud. </p> <div data-target="otp" className="mt-5 flex gap-2"> {[0, 1, 2, 3, 4, 5].map((i) => ( <span key={i} className="h-11 w-9 rounded-[8px] bg-kura-surface" style={{ boxShadow: i === 0 ? "0 0 0 1px var(--kura-accent), 0 0 0 3px var(--kura-ring)" : "0 0 0 1px var(--kura-border-strong)", }} /> ))} </div> <span className="mt-5 flex h-9 w-full items-center justify-center rounded-[8px] bg-kura-ink font-medium text-[13px] text-kura-fg-inverted"> Verify </span> <span className="mt-3 text-[12px] text-kura-fg-subtle">Use a recovery code instead</span> </div> </div> ); } export function BrowserSessionPaused() { const [paused, setPaused] = React.useState(true); const [startedAt] = React.useState(() => Date.now() - 9 * 60_000 - 41_000); return ( <BrowserSession className="w-full max-w-4xl" url="https://cloud.acme.dev/login/two-factor?next=%2Fweb%2Fdeployments" title="Sign in · Acme Cloud" viewport={{ width: W, height: H }} status={paused ? "paused" : "browsing"} statusText={paused ? "Enter the 2FA code, then hand back" : undefined} startedAt={startedAt} cursor={at(300, 262)} cursorLabel="Kura" highlight={box(264, 226, 272, 58, "input[autocomplete=one-time-code]")} onResume={() => setPaused(false)} onTakeOver={() => setPaused(true)} steps={[ { id: "1", kind: "navigate", label: "Open the preview", status: "done", detail: "cloud.acme.dev/web/deployments", }, { id: "2", kind: "click", label: "Continue with GitHub", status: "done", detail: 'button[data-provider="github"]', }, { id: "3", kind: "type", label: "Enter the 2FA code", status: paused ? "waiting" : "running", detail: "Needs a code only you have", }, { id: "4", kind: "extract", label: "Check the login page", status: "queued", detail: "/login", }, ]} > <TwoFactorPage /> </BrowserSession> ); } ``` ### Under the plan (composition) A narrow stacked session under a TaskList, as in a run sidebar. ```tsx import { Check, GitPullRequest } from "lucide-react"; import { TaskList } from "@kura-ui/react/task-list"; import { BrowserSession } from "@kura-ui/react/browser-session"; const W = 800; const H = 500; const at = (x: number, y: number) => ({ x: (x / W) * 100, y: (y / H) * 100 }); const box = (x: number, y: number, w: number, h: number, label?: string) => ({ x: (x / W) * 100, y: (y / H) * 100, width: (w / W) * 100, height: (h / H) * 100, label, }); function PullRequestPage() { return ( <div className="h-[500px] bg-kura-surface font-kura-sans text-kura-fg"> <SiteBar /> <div className="px-8 pt-6"> <h1 data-target="pr-h1" className="font-semibold text-[20px] leading-7 tracking-[-0.015em]"> {PR_TITLE} <span className="font-normal text-kura-fg-subtle">#482</span> </h1> <div className="mt-2 flex items-center gap-2 text-[13px] text-kura-fg-muted"> <span className="flex items-center gap-1 rounded-full bg-kura-success/15 px-2 py-0.5 font-medium text-[12px] text-kura-success-text"> <GitPullRequest className="size-3" strokeWidth={2} /> Open </span> <span> <span className="font-medium text-kura-fg">kura</span> wants to merge 4 commits into{" "} <span className="font-kura-mono text-[12px]">main</span> from{" "} <span className="font-kura-mono text-[12px]">kura/auth-client</span> </span> </div> <div className="mt-4 flex gap-5 border-kura-border-subtle border-b text-[13px] text-kura-fg-muted"> <span className="-mb-px border-kura-fg border-b-2 pb-2 font-medium text-kura-fg"> Conversation </span> <span>Commits 4</span> <span>Checks 3</span> <span>Files changed 6</span> </div> <div className="mt-4 rounded-[10px] p-4 text-[13px] text-kura-fg-muted leading-5 shadow-kura-xs"> {PR_BODY} </div> <div className="mt-3 flex flex-col rounded-[10px] text-[13px] shadow-kura-xs"> <div className="flex h-10 items-center gap-2 border-kura-border-subtle border-b px-4 font-medium"> <Check className="size-4 text-kura-success" strokeWidth={2.25} /> All checks have passed </div> {[ ["test", "142 passed · 41s"], ["typecheck", "0 errors · 18s"], ["lint", "clean · 6s"], ].map(([name, meta]) => ( <div key={name} className="flex h-9 items-center gap-2 px-4"> <Check className="size-3.5 text-kura-success" strokeWidth={2.25} /> <span className="font-kura-mono text-[12.5px]">{name}</span> <span className="ml-auto font-kura-mono text-[12px] text-kura-fg-subtle">{meta}</span> </div> ))} </div> </div> </div> ); } const PR_URL = "https://github.com/acme/web/pull/482"; const PR_TITLE = "Migrate session API to @acme/auth client"; const PR_BODY = "Replaces fetchUser() and the legacy /api/session REST calls with createAuthClient(). Refreshes expired sessions with the rotated token."; function SiteBar() { return ( <div className="flex h-12 items-center gap-3 border-kura-border-subtle border-b px-8 text-[14px]"> <span className="size-5 rounded-[5px] bg-kura-fg" /> <span className="text-kura-fg-muted">acme</span> <span className="text-kura-fg-subtle">/</span> <span className="font-semibold">web</span> <span className="ml-auto flex items-center gap-5 text-[13px] text-kura-fg-muted"> <span>Code</span> <span className="font-medium text-kura-fg">Pull requests</span> <span>Actions</span> <span className="size-6 rounded-full bg-kura-gray-5" /> </span> </div> ); } export function BrowserSessionComposition() { return ( <div className="flex w-full max-w-md flex-col gap-3"> <TaskList title="Plan" collapseCompleted={false} items={[ { id: "t", title: "Run pnpm test", status: "done", durationMs: 36_800 }, { id: "p", title: "Open pull request", status: "running", detail: "via the browser" }, { id: "s", title: "Summarize the run", status: "queued" }, ]} /> <BrowserSession layout="stacked" url={PR_URL} title="Migrate session API · acme/web" viewport={{ width: W, height: H }} cursor={at(468, 94)} cursorLabel="Kura" highlight={box(24, 66, 478, 40, "h1 · #482")} steps={[ { id: "a", kind: "click", label: "Click “Create pull request”", status: "done" }, { id: "b", kind: "extract", label: "Read the PR number", status: "running", detail: "h1", }, ]} > <PullRequestPage /> </BrowserSession> </div> ); } ``` ## Dependencies - npm: `lucide-react` - Kura registry items: `kura-theme`, `button`, `kura-format`, `shimmer-text`, `status-glyph`, `use-elapsed`, `utils` - Related: `terminal`, `task-list`, `run-header`, `approval-prompt`, `tool-call` --- # 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 = solid ink call to action; secondary = soft grey fill; outline = surface with a hairline; ghost = no chrome until hover; 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.98 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 { GitBranch, Play, Plus, Trash2 } from "lucide-react"; import { Button } from "@kura-ui/react/button"; export function ButtonFull() { return ( <div className="flex flex-col items-center gap-5"> <div className="flex flex-wrap items-center justify-center gap-2"> <Button variant="primary">Deploy</Button> <Button variant="secondary">Edit prompt</Button> <Button variant="outline"> <GitBranch /> Branch chat </Button> <Button variant="ghost">Skip</Button> <Button variant="accent"> <Play /> 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"> <Plus /> Tag </Button> <Button size="sm" variant="outline"> Small </Button> <Button size="md" variant="outline"> Medium </Button> <Button size="lg" variant="outline"> 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 ( <div className="flex items-center gap-2"> <Button asChild> <a href="https://github.com/Absterrg0/Kura-UI#readme">Get started</a> </Button> <Button asChild variant="outline"> <a href="https://github.com/Absterrg0/Kura-UI"> View source <ArrowUpRight /> </a> </Button> </div> ); } ``` ## Dependencies - npm: `radix-ui` - Kura registry items: `kura-theme`, `spinner`, `utils` - Related: `icon-button`, `kbd-shortcut`, `tooltip` --- # Checkpoints > Restore points across an agent run: a compact rail of auto and saved checkpoints with relative times, a current marker and inline-confirmed Restore. - **Slug:** `checkpoints` · **Category:** agent · **Status:** experimental - **Import:** `import { Checkpoint, Checkpoints } from "@kura-ui/react/checkpoints";` - **Docs:** https://kuro.abstergo.fyi/components/checkpoints - **Registry item:** https://kuro.abstergo.fyi/r/checkpoints.json - **Tags:** agent, checkpoint, restore, rewind, undo, history, snapshot ## Install ```bash # shadcn registry (copies source into your project) npx shadcn@latest add https://kuro.abstergo.fyi/r/checkpoints.json # Kura CLI (same, plus dependency resolution and --json output) npx @kura-ui/cli add checkpoints # npm package npm install @kura-ui/react ``` ## When to use - A coding agent snapshots the workspace before edits (Claude Code rewind, Cursor checkpoints) and the human should be able to roll files back. - Showing where the workspace is after a rewind: checkpoints newer than the current one read as undone and can be restored forward. - Letting people save a manual checkpoint before a risky step (onCreate). ## When not to use - The agent's plan or steps — use task-list or agent-timeline. - Reviewing what changed in files — use diff-view or file-changes. - Git history or commits — this is for harness snapshots, not a commit log. ## Props | Prop | Type | Default | Required | Description | | --- | --- | --- | --- | --- | | `checkpoints` | `Checkpoint[]` | — | yes | { id, label, at, filesChanged?, kind: 'auto' \| 'manual', current? }, newest first. Mark exactly one current. | | `title` | `React.ReactNode` | `"Checkpoints"` | no | Header title; the count follows it. | | `onRestore` | `(id: string) => void \| Promise<void>` | — | no | Restore handler, called after the inline confirm. Return a promise to show a spinner until it settles. Without it no Restore buttons render. | | `onCreate` | `() => void` | — | no | Shows 'Save checkpoint' in the header. Add a kind:'manual' checkpoint marked current. | | `confirm` | `boolean` | `true` | no | Ask inline before restoring. false calls onRestore directly. | | `empty` | `React.ReactNode` | — | no | Replaces the default empty state ('No checkpoints yet'). | Native attributes of the root element, `className` and `ref` are passed through. ## Anatomy - **Checkpoints** (`data-slot="checkpoints"`) — Root panel (a size container). - **Header** (`data-slot="checkpoints-header"`) — Title, count and the optional checkpoints-create button. - **Item** (`data-slot="checkpoints-item"`) — <li> with `data-kind`, `data-current`, `data-ahead` (newer than current = undone) and `data-state='confirming'`. Node on a hairline rail: hollow ring = auto, diamond = saved, ink dot with halo = current. - **Label** (`data-slot="checkpoints-label"`) — What the agent had just done. Truncates. - **Current** (`data-slot="checkpoints-current"`) — 'Current' pill. - **Files** (`data-slot="checkpoints-files"`) — '3 files' in mono (hidden when narrow). - **Restore** (`data-slot="checkpoints-restore"`) — Ghost button that swaps in for the relative time on hover/focus (always visible on touch); aria-expanded when confirming. - **Confirm** (`data-slot="checkpoints-confirm"`) — Inline confirm under the row: what will be undone (or re-applied), Cancel and Restore. - **Empty** (`data-slot="checkpoints-empty"`) — Empty state. ## Accessibility - Role: `list (ol)` - An ordered list labelled by the title. Times are <time datetime> with the absolute time as a tooltip. - Restore buttons are named 'Restore to <label>'. Opening the confirm moves focus to its Restore button; Escape or Cancel closes it and returns focus to the trigger. - Undone checkpoints carry visually hidden '(undone)'. A polite status region announces 'Restored to …'. - Relative times render after mount only, so server and client markup match. - Reduced motion: Rows fade in without rising; the confirm opens with a fade instead of a height transition. | Keys | Action | | --- | --- | | Tab | Reach each Restore button (it becomes visible on focus) | | Enter / Space | Open the inline confirm, then confirm | | Escape | Cancel the confirm | ## Notes for agents - Pass checkpoints newest first and mark exactly one current; the component uses `at` to work out which are undone. - Restore only rewinds files in your harness; keep the conversation and say so in your UI copy if that differs. - Make onRestore async when restoring takes time so the confirm shows a spinner and blocks double restores. ## Examples ### Three checkpoints (minimal) ```tsx "use client"; import * as React from "react"; import { type Checkpoint, Checkpoints } from "@kura-ui/react/checkpoints"; const sec = (s: number) => Date.now() - s * 1000; export function CheckpointsMinimal() { const [checkpoints] = React.useState<Checkpoint[]>(() => [ { id: "c3", label: "Patched src/middleware.ts", at: sec(70), filesChanged: 1, kind: "auto", current: true, }, { id: "c2", label: "Replaced fetchUser() in 9 files", at: sec(260), filesChanged: 9, kind: "auto", }, { id: "c1", label: "Run started on kura/auth-client", at: sec(690), kind: "auto" }, ]); return <Checkpoints className="w-full max-w-md" checkpoints={checkpoints} onRestore={() => {}} />; } ``` ### Live, with save and restore (full) A new automatic checkpoint lands while you watch; Restore confirms inline and resolves after a simulated 900ms; Save checkpoint adds a manual one. ```tsx "use client"; import * as React from "react"; import { type Checkpoint, Checkpoints } from "@kura-ui/react/checkpoints"; function storyline(): Checkpoint[] { return [ { id: "tests", label: "Updated login and session tests", at: sec(150), filesChanged: 3, kind: "auto", current: true, }, { id: "mw", label: "Patched src/middleware.ts", at: sec(290), filesChanged: 1, kind: "auto" }, { id: "manual", label: "Before middleware changes", at: sec(370), kind: "manual" }, { id: "client", label: "Replaced fetchUser() with auth.getSession()", at: sec(430), filesChanged: 9, kind: "auto", }, { id: "start", label: "Run started on kura/auth-client", at: sec(720), kind: "auto" }, ]; } const sec = (s: number) => Date.now() - s * 1000; export function CheckpointsFull() { const [checkpoints, setCheckpoints] = React.useState<Checkpoint[]>(storyline); // The agent keeps working: a new automatic checkpoint lands a moment after mount. React.useEffect(() => { const t = setTimeout(() => { setCheckpoints((list) => [ { id: "fix", label: "Fixed expired-session refresh in src/auth/client.ts", at: Date.now(), filesChanged: 1, kind: "auto", current: true, }, ...list.map((c) => ({ ...c, current: false })), ]); }, 1800); return () => clearTimeout(t); }, []); const restore = (id: string) => new Promise<void>((resolve) => setTimeout(() => { setCheckpoints((list) => list.map((c) => ({ ...c, current: c.id === id }))); resolve(); }, 900), ); const save = () => setCheckpoints((list) => { const current = list.find((c) => c.current); return [ { id: `manual-${list.length}`, label: current ? `Saved after “${current.label}”` : "Saved checkpoint", at: Date.now(), kind: "manual" as const, current: true, }, ...list.map((c) => ({ ...c, current: false })), ]; }); return ( <Checkpoints className="w-full max-w-lg" checkpoints={checkpoints} onRestore={restore} onCreate={save} /> ); } ``` ### After a rewind (state) The current checkpoint is in the middle; newer ones read as undone and can be restored forward. ```tsx "use client"; import * as React from "react"; import { type Checkpoint, Checkpoints } from "@kura-ui/react/checkpoints"; function storyline(): Checkpoint[] { return [ { id: "tests", label: "Updated login and session tests", at: sec(150), filesChanged: 3, kind: "auto", current: true, }, { id: "mw", label: "Patched src/middleware.ts", at: sec(290), filesChanged: 1, kind: "auto" }, { id: "manual", label: "Before middleware changes", at: sec(370), kind: "manual" }, { id: "client", label: "Replaced fetchUser() with auth.getSession()", at: sec(430), filesChanged: 9, kind: "auto", }, { id: "start", label: "Run started on kura/auth-client", at: sec(720), kind: "auto" }, ]; } const sec = (s: number) => Date.now() - s * 1000; export function CheckpointsRestored() { const [checkpoints, setCheckpoints] = React.useState<Checkpoint[]>(() => storyline().map((c) => ({ ...c, current: c.id === "manual" })), ); return ( <Checkpoints className="w-full max-w-lg" checkpoints={checkpoints} onRestore={(id) => setCheckpoints((l) => l.map((c) => ({ ...c, current: c.id === id })))} /> ); } ``` ### Empty (state) ```tsx import { Checkpoints } from "@kura-ui/react/checkpoints"; export function CheckpointsEmpty() { return <Checkpoints className="w-full max-w-md" checkpoints={[]} />; } ``` ### With run-header (composition) Restoring rewinds the run's step count and pauses it; Resume returns to the latest checkpoint. ```tsx "use client"; import * as React from "react"; import { RunHeader } from "@kura-ui/react/run-header"; import { type Checkpoint, Checkpoints } from "@kura-ui/react/checkpoints"; const sec = (s: number) => Date.now() - s * 1000; function storyline(): Checkpoint[] { return [ { id: "tests", label: "Updated login and session tests", at: sec(150), filesChanged: 3, kind: "auto", current: true, }, { id: "mw", label: "Patched src/middleware.ts", at: sec(290), filesChanged: 1, kind: "auto" }, { id: "manual", label: "Before middleware changes", at: sec(370), kind: "manual" }, { id: "client", label: "Replaced fetchUser() with auth.getSession()", at: sec(430), filesChanged: 9, kind: "auto", }, { id: "start", label: "Run started on kura/auth-client", at: sec(720), kind: "auto" }, ]; } const STEP_OF: Record<string, number> = { tests: 5, mw: 4, manual: 3, client: 3, start: 0 }; export function CheckpointsComposition() { const [startedAt] = React.useState(() => sec(744)); const [checkpoints, setCheckpoints] = React.useState<Checkpoint[]>(storyline); const current = checkpoints.find((c) => c.current)?.id ?? "tests"; const rewound = current !== "tests"; return ( <div className="flex w-full max-w-xl flex-col gap-2"> <RunHeader variant="bar" title="Migrate session API to @acme/auth" status={rewound ? "paused" : "running"} startedAt={startedAt} progress={{ done: STEP_OF[current] ?? 0, total: 7 }} cost={1.46} budget={5} onPause={() => {}} onResume={() => setCheckpoints((l) => l.map((c) => ({ ...c, current: c.id === "tests" })))} onStop={() => {}} shortcuts={false} /> <Checkpoints checkpoints={checkpoints} onRestore={(id) => setCheckpoints((l) => l.map((c) => ({ ...c, current: c.id === id })))} /> </div> ); } ``` ## Dependencies - npm: `lucide-react` - Kura registry items: `kura-theme`, `button`, `utils` - Related: `run-header`, `diff-view`, `file-changes`, `task-list` --- # 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: "AbortController – Web APIs", url: "https://developer.mozilla.org/en-US/docs/Web/API/AbortController", siteName: "MDN", snippet: "The AbortController interface represents a controller object that allows you to abort one or more Web requests as and when desired.", }, ]; 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: "AbortController – Web APIs", url: "https://developer.mozilla.org/en-US/docs/Web/API/AbortController", siteName: "MDN", snippet: "The AbortController interface represents a controller object that allows you to abort one or more Web requests as and when desired.", }, ]; export function CitationFull() { return ( <div className="flex w-full max-w-xl flex-col gap-4"> <p className="text-[15px] text-kura-fg leading-relaxed"> Render the new count immediately with{" "} <code className="rounded-kura-xs bg-kura-active px-[0.3em] py-[0.1em] font-kura-mono text-[0.86em]"> 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 abort the stale request if the reader taps again <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: "AbortController – Web APIs", url: "https://developer.mozilla.org/en-US/docs/Web/API/AbortController", siteName: "MDN", snippet: "The AbortController interface represents a controller object that allows you to abort one or more Web requests as and when desired.", }, ]; 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: "AbortController – Web APIs", url: "https://developer.mozilla.org/en-US/docs/Web/API/AbortController", siteName: "MDN", snippet: "The AbortController interface represents a controller object that allows you to abort one or more Web requests as and when desired.", }, ]; 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). - The default palette is deliberately quiet: grey value carries structure (keywords/attributes fg-muted, punctuation/comments fg-subtle) and only strings, numbers and types get a low-chroma tint. Theme it with CSS variables on any ancestor: --kura-syntax-keyword, -string, -constant, -function, -type, -tag, -attr, -property, -comment, -punctuation. - `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. ```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); return ( <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 header className="w-full max-w-xl" /> ); } ``` ### 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 (opaque raised surface over a dimming scrim, 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 type { AttachmentItem } from "@kura-ui/react/attachment"; import { KbdShortcut } from "@kura-ui/react/kbd-shortcut"; 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 aria-pressed:shadow-[inset_0_0_0_1px_var(--kura-border-subtle)] [&_svg]:size-3.5" > {icon} {children} </button> ); } const boardFiles: AttachmentItem[] = [ { id: "deck", name: "q3-board-deck.pdf", type: "application/pdf", size: 4_820_000 }, { id: "cohorts", name: "churn-by-cohort.csv", type: "text/csv", size: 312_000 }, ]; export function ComposerFull() { const [value, setValue] = React.useState( "Check the churn figures on slide 7 against the cohort CSV and flag anything that doesn’t reconcile.", ); const [status, setStatus] = React.useState<ComposerStatus>("idle"); const [model, setModel] = React.useState("sonnet"); const [search, setSearch] = React.useState(false); const [think, setThink] = React.useState(true); 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-2.5"> <Composer value={value} onValueChange={setValue} defaultAttachments={boardFiles} status={status} maxLength={4000} 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="Ask about these files, or drop more…" minRows={2} maxRows={10} /> <ComposerToolbar> <ComposerTools> <ComposerAttachButton /> <ModelPicker models={models} value={model} onValueChange={setModel} side="top" /> <span aria-hidden className="mx-0.5 h-4 w-px bg-kura-border" /> <ToolToggle pressed={think} onPressedChange={setThink} icon={<Lightbulb />}> Think </ToolToggle> <ToolToggle pressed={search} onPressedChange={setSearch} icon={<Globe />}> Search </ToolToggle> </ComposerTools> <ComposerActions> <ComposerHint showAt={0.8} /> <ComposerSubmit /> </ComposerActions> </ComposerToolbar> </Composer> <div className="flex min-h-5 items-center justify-between gap-3 px-1.5"> <p className="truncate text-kura-fg-subtle text-xs" aria-live="polite"> {status === "submitted" ? "Sending…" : status === "streaming" ? "Responding · Esc to stop" : last ? `Sent with ${last.attachments.length} ${last.attachments.length === 1 ? "file" : "files"}` : "Kura reads attachments in full; tables over 50k rows are sampled."} </p> <div className="hidden shrink-0 items-center gap-3 sm:flex"> <KbdShortcut keys={["enter"]} label="Send" variant="ghost" /> <KbdShortcut keys={["shift", "enter"]} label="New line" variant="ghost" /> </div> </div> </div> ); } ``` ### Submitted, streaming, over limit and disabled (state) ```tsx import * as React from "react"; import { Composer, ComposerActions, ComposerAttachButton, ComposerHint, ComposerInput, ComposerSubmit, ComposerToolbar, ComposerTools } from "@kura-ui/react/composer"; function StateLabel({ children }: { children: React.ReactNode }) { return <p className="px-1.5 pb-1.5 font-medium text-kura-fg-subtle text-xs">{children}</p>; } export function ComposerStates() { return ( <div className="flex w-full max-w-xl flex-col gap-5"> <div> <StateLabel>Submitted — waiting for the first token</StateLabel> <Composer defaultValue="Summarise the attached incident report for the #eng-oncall channel." status="submitted" > <ComposerInput /> <ComposerToolbar> <ComposerTools> <ComposerAttachButton /> </ComposerTools> <ComposerActions> <ComposerSubmit /> </ComposerActions> </ComposerToolbar> </Composer> </div> <div> <StateLabel>Streaming, close to the character limit</StateLabel> <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> </div> <div> <StateLabel>Disabled</StateLabel> <Composer disabled placeholder="You’ve reached this week’s Opus limit. Resets Monday at 09:00." /> </div> </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-[-0.02em]"> 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} />; } ``` ### Thread header with a breakdown (full) A ring in the thread header and a bar with a footer note, both with the segment breakdown on hover. Attach logs to watch the numbers roll into warning and danger. ```tsx "use client"; import { Paperclip } 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 [logs, setLogs] = React.useState(0); const segments = BASE.map((s) => s.id === "files" ? { ...s, tokens: s.tokens + logs * 24_000 } : s, ); return ( <div 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 py-3"> <div className="flex min-w-0 flex-col gap-0.5"> <span className="truncate font-medium text-kura-fg text-sm tracking-[-0.01em]"> Auth middleware refactor </span> <span className="text-kura-fg-subtle text-xs">32 turns · 200k context window</span> </div> <ContextMeter max={200_000} segments={segments} variant="ring" valueDisplay="percent" warningAt={0.7} dangerAt={0.9} label="Context" /> </div> <div className="flex items-center justify-between gap-3 px-4 py-3 shadow-[inset_0_1px_0_var(--kura-border-subtle)]"> <ContextMeter max={200_000} segments={segments} variant="bar" valueDisplay="tokens" className="-ml-1.5" footer="Files count once per turn; tool definitions are cached." /> <div className="flex items-center gap-1"> {logs > 0 && ( <Button variant="ghost" size="xs" onClick={() => setLogs(0)}> Clear </Button> )} <Button variant="secondary" size="xs" onClick={() => setLogs((n) => n + 1)}> <Paperclip /> Attach server.log </Button> </div> </div> </div> ); } ``` ### Thresholds (state) ok, warning and danger bars in a list of threads, each labelled by its thread. ```tsx import { ContextMeter } from "@kura-ui/react/context-meter"; const THREADS = [ { title: "Onboarding emails", used: 52_000 }, { title: "Q3 data migration", used: 98_500 }, { title: "Incident review: checkout", used: 121_900 }, ]; export function ContextMeterThresholds() { return ( <ul className="flex w-full max-w-md flex-col"> {THREADS.map((t) => ( <li key={t.title} className="flex h-10 items-center justify-between gap-4 text-[13px] text-kura-fg shadow-[inset_0_-1px_0_var(--kura-border-subtle)] last:shadow-none" > <span className="min-w-0 truncate">{t.title}</span> <ContextMeter max={128_000} used={t.used} variant="bar" label={t.title} /> </li> ))} </ul> ); } ``` ### In a composer footer (composition) Next to the attach and send IconButtons of a composer. ```tsx import { ArrowUp, Paperclip } 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"> <div className="flex items-center gap-1"> <IconButton label="Attach files" size="sm" icon={<Paperclip />} /> <ContextMeter max={200_000} segments={BASE} /> </div> <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` --- # Diff View > Code review for agent edits: a parsed unified diff with syntax and word highlights, line numbers, and per-hunk Accept / Reject with j/k/a/r keys. - **Slug:** `diff-view` · **Category:** workspace · **Status:** experimental - **Import:** `import { DiffFile, DiffFileInput, DiffFileStatus, DiffHunk, DiffHunkInput, DiffLine, DiffLineKind, DiffReview, DiffReviewChange, DiffView, HunkDecision } from "@kura-ui/react/diff-view";` - **Docs:** https://kuro.abstergo.fyi/components/diff-view - **Registry item:** https://kuro.abstergo.fyi/r/diff-view.json - **Tags:** diff, code-review, patch, git, accept-reject, agent, syntax-highlighting, workspace ## Install ```bash # shadcn registry (copies source into your project) npx shadcn@latest add https://kuro.abstergo.fyi/r/diff-view.json # Kura CLI (same, plus dependency resolution and --json output) npx @kura-ui/cli add diff-view # npm package npm install @kura-ui/react ``` ## When to use - Let a user review the edits a coding agent made (Claude Code, Codex, Cursor-style) before applying or committing them. - Show `git diff` / `git show` output or a model-written patch as a readable, highlighted diff. - Per-change approval: accept or reject individual hunks, a whole file, or everything, and act on the resulting decisions. - A read-only diff of what changed in a run (reviewable={false}). ## When not to use - Listing which files changed without showing contents — use file-changes (it composes well beside DiffView). - Showing a single code snippet or a whole file — use code-block. - Command or test output — use terminal. - Approving a tool call or command before it runs — use approval-prompt. ## Props | Prop | Type | Default | Required | Description | | --- | --- | --- | --- | --- | | `diff` | `string` | — | no | A unified diff (`git diff`, `git show`, `diff -u`, a model's patch). Parsed with parseUnifiedDiff: renames, new/deleted/binary files, quoted paths, CRLF, missing counts, `\ No newline at end of file`, and wrong hunk counts are handled. Ignored when `files` is given. | | `files` | `readonly DiffFileInput[]` | — | no | Structured files `{ path, oldPath?, status?, language?, binary?, hunks: [{ id?, oldStart?, newStart?, section?, lines }] }`. `lines` may be DiffLine objects or raw strings ("+added", "-removed", " context"); line numbers are computed. | | `title` | `React.ReactNode` | `"Changes"` | no | Header title. | | `reviewable` | `boolean` | `true` | no | Show per-hunk Accept / Reject, per-file Accept file, Accept all / Reject all and the “2 of 5 reviewed” tally. | | `review` | `DiffReview` | — | no | Decisions (controlled): `{ [hunkId]: "accepted" \| "rejected" }`; absent = pending. Hunk ids are `hunk.id` or `<path>#<index>` (see hunkId()). | | `defaultReview` | `DiffReview` | `{}` | no | Initial decisions when uncontrolled. | | `onReviewChange` | `(review: DiffReview, change: DiffReviewChange) => void` | — | no | Called with the full next review state and `{ path, hunkIds, decision }` where decision is "accepted", "rejected" or "pending" (undo). | | `collapsed` | `readonly string[]` | — | no | Collapsed file paths (controlled). | | `defaultCollapsed` | `readonly string[]` | `[]` | no | Initially collapsed file paths when uncontrolled. | | `onCollapsedChange` | `(collapsed: string[]) => void` | — | no | Called when a file is collapsed or expanded (by click or by collapseReviewed). | | `collapseReviewed` | `boolean` | `true` | no | Collapse a file once every hunk in it has a decision (like GitHub's “Viewed”). | | `autoAdvance` | `boolean` | `true` | no | After a decision, move focus to the next pending hunk (Cursor-style review flow). | | `wrap` | `boolean` | `false` | no | Soft-wrap long lines instead of scrolling each hunk sideways. | | `maxHeight` | `number` | — | no | Scroll the files inside this height (px). File headers stay pinned while scrolling (also against page scroll without it). | | `actions` | `React.ReactNode` | — | no | Extra controls at the end of the header, e.g. a Commit button. | | `empty` | `React.ReactNode` | — | no | Rendered when there are no files. Default an icon + “No changes”. | Native attributes of the root element, `className` and `ref` are passed through. ## Anatomy - **DiffView** (`data-slot="diff-view"`) — `data-state="empty" | "pending" | "reviewed"`, `data-reviewable`. A container query hides secondary header items below ~26–34rem. - **Header** (`data-slot="diff-view-header"`) — Title, mono summary (`diff-view-summary`: files, +N −M), review progress (`diff-view-progress`) and Accept all / Reject all. - **File** (`data-slot="diff-view-file"`) — `<section aria-label={path}>` with `data-status="added" | "modified" | "deleted" | "renamed"` and `data-state="open" | "closed"`. - **FileHeader** (`data-slot="diff-view-file-header"`) — Sticky row: collapse toggle (button, aria-expanded), path (`diff-view-path`: dim directory + bold name, old → new for renames), status chip, +N −M, 5-block ratio bar (`diff-view-ratio`), Accept file / review state (`diff-view-file-review`). - **Hunk** (`data-slot="diff-view-hunk"`) — `role="group"`, roving tabindex, `data-hunk-id`, `data-review="pending" | "accepted" | "rejected"`. Accent bar on the left when focused. - **HunkHeader** (`data-slot="diff-view-hunk-header"`) — `@@ −a,b +c,d @@` + section heading, and Reject / Accept (`diff-view-hunk-actions`) or the decision (`diff-view-hunk-state`) with Undo. - **Line** (`data-slot="diff-view-line"`) — `data-kind="context" | "add" | "remove"`: old and new line numbers, sign, highlighted code with word-level change marks. ## Accessibility - Each file is a labelled section; its header toggle is a button with aria-expanded/aria-controls. - Hunks are focusable groups named “Change 2 of 9, src/auth/client.ts lines 10–19, pending review”; only the current hunk (and its buttons) is in the Tab order. - Added/removed lines carry sr-only “added:” / “removed:” prefixes; colour is never the only signal (+/− signs, status chips, labels). - Decisions are announced in a polite status region (“Accepted hunk in src/middleware.ts. 3 of 9 reviewed.”) — once per action, never per render. - Accept / Reject tooltips show their single-key shortcuts. - Reduced motion: Chevron rotation, the review-dimming fade and the progress colour change apply instantly; no motion is essential. | Keys | Action | | --- | --- | | J / K | Next / previous hunk (skips collapsed files) | | A | Accept the focused hunk, then move to the next pending one | | R | Reject the focused hunk, then move to the next pending one | | U / Backspace | Undo the focused hunk's decision | | Enter / Space | On a file header: collapse or expand the file | | Tab | Through file headers and the focused hunk's buttons | ## Notes for agents - Pass the raw `git diff` string to `diff`; don't pre-split it. Use `files` when you already have structured hunks (raw '+'/'-'/' ' strings are fine as lines). - Review state is keyed by hunk id: `hunk.id` if you set one (do this when hunks can shift, e.g. while an agent keeps editing), else `<path>#<index>`. Export `hunkId(file, hunk, index)` to compute it. - To apply decisions, walk parseUnifiedDiff(diff) and keep hunks whose id is "accepted"; rejected and pending hunks are not applied. - Helpers exported alongside: parseUnifiedDiff, normalizeFiles, wordDiff, countChanges, languageFromPath. - Syntax highlighting uses code-block's synchronous highlighter; the language is inferred from the file extension (override with files[].language). - Very large diffs render every line; collapse big files with defaultCollapsed (e.g. lockfiles) to keep it fast. ## Examples ### Basic (minimal) One file from a unified diff string, with per-hunk review. ```tsx import { DiffView } from "@kura-ui/react/diff-view"; const MIDDLEWARE_DIFF = `diff --git a/src/middleware.ts b/src/middleware.ts --- a/src/middleware.ts +++ b/src/middleware.ts @@ -1,4 +1,4 @@ import { NextResponse, type NextRequest } from "next/server"; -import { readSessionCookie } from "@/lib/legacy-session"; +import { auth } from "@/auth/client"; const PUBLIC_PATHS = ["/login", "/signup", "/api/health"]; @@ -8,5 +8,5 @@ export async function middleware(request: NextRequest) { if (PUBLIC_PATHS.some((p) => pathname.startsWith(p))) return NextResponse.next(); - const session = readSessionCookie(request.headers.get("cookie")); + const session = await auth.getSession({ headers: request.headers }); if (!session) { const url = new URL("/login", request.url); `; export function DiffViewMinimal() { return <DiffView diff={MIDDLEWARE_DIFF} className="w-full max-w-2xl" />; } ``` ### Review session (full) The agent's whole migration (4 files, 9 hunks) with controlled review state, a scrolling body, pinned file headers and a keyboard legend. Try j, k, a, r, u. ```tsx "use client"; import * as React from "react"; import { Kbd } from "@kura-ui/react/kbd"; import { type DiffReview, DiffView } from "@kura-ui/react/diff-view"; const AUTH_MIGRATION_DIFF = `diff --git a/src/auth/client.ts b/src/auth/client.ts index 887cccf..1c08d5a 100644 --- a/src/auth/client.ts +++ b/src/auth/client.ts @@ -1,7 +1,8 @@ import { cache } from "react"; -import { fetchJson } from "@/lib/http"; -import type { Session, User } from "./types"; +import { createAuthClient, type Session, type User } from "@acme/auth"; -const SESSION_URL = "/api/v1/session"; -const REFRESH_URL = "/api/v1/session/refresh"; +export const auth = createAuthClient({ + baseUrl: process.env.NEXT_PUBLIC_AUTH_URL, + refresh: "auto", +}); @@ -9,14 +10,10 @@ const REFRESH_URL = "/api/v1/session/refresh"; export const fetchUser = cache(async (): Promise<User | null> => { - const res = await fetchJson<Session>(SESSION_URL, { credentials: "include" }); - if (!res.ok) return null; - return res.data.user; + const session = await auth.getSession(); + return session?.user ?? null; }); -export async function refreshSession(token: string): Promise<Session> { - const res = await fetchJson<Session>(REFRESH_URL, { - method: "POST", - body: JSON.stringify({ token }), - }); - if (!res.ok) throw new Error(\`refresh failed: \${res.status}\`); - return res.data; +export async function refreshSession(session: Session): Promise<Session> { + const next = await auth.refresh(session.refreshToken); + if (!next) throw new Error("refresh failed: session revoked"); + return next; } @@ -24,3 +21,3 @@ export async function refreshSession(token: string): Promise<Session> { export function isExpired(session: Session, now = Date.now()): boolean { - return session.expiresAt < now; + return session.expiresAt <= now; } @@ -28,3 +25,3 @@ export function isExpired(session: Session, now = Date.now()): boolean { export async function signOut(): Promise<void> { - await fetchJson(SESSION_URL, { method: "DELETE", credentials: "include" }); + await auth.signOut(); } diff --git a/src/auth/__tests__/login.test.ts b/src/auth/__tests__/login.test.ts index 9fe0aaf..711a4bd 100644 --- a/src/auth/__tests__/login.test.ts +++ b/src/auth/__tests__/login.test.ts @@ -1,4 +1,4 @@ import { describe, expect, it, vi } from "vitest"; -import { refreshSession, isExpired } from "../client"; +import { auth, isExpired, refreshSession } from "../client"; describe("login", () => { @@ -8,8 +8,10 @@ describe("login", () => { it("refreshes an expired session", async () => { - vi.spyOn(globalThis, "fetch").mockResolvedValue( - new Response(JSON.stringify({ expiresAt: 10, user: { id: "u_1" } })), - ); - const next = await refreshSession("tok_expired"); + vi.spyOn(auth, "refresh").mockResolvedValue({ + expiresAt: 10, + refreshToken: "tok_next", + user: { id: "u_1" }, + } as never); + const next = await refreshSession({ refreshToken: "tok_expired" } as never); expect(next.user.id).toBe("u_1"); }); diff --git a/src/lib/legacy-session.ts b/src/lib/legacy-session.ts deleted file mode 100644 index f0ae86d..0000000 --- a/src/lib/legacy-session.ts +++ /dev/null @@ -1,10 +0,0 @@ -/** @deprecated Use \`auth.getSession()\` from @acme/auth. */ -export function readSessionCookie(cookie: string | null) { - const raw = cookie?.match(/acme_session=([^;]+)/)?.[1]; - if (!raw) return null; - try { - return JSON.parse(atob(raw)) as { userId: string; expiresAt: number }; - } catch { - return null; - } -} diff --git a/src/middleware.ts b/src/middleware.ts index 0e93409..7eda2e2 100644 --- a/src/middleware.ts +++ b/src/middleware.ts @@ -1,4 +1,4 @@ import { NextResponse, type NextRequest } from "next/server"; -import { readSessionCookie } from "@/lib/legacy-session"; +import { auth } from "@/auth/client"; const PUBLIC_PATHS = ["/login", "/signup", "/api/health"]; @@ -8,5 +8,5 @@ export async function middleware(request: NextRequest) { if (PUBLIC_PATHS.some((p) => pathname.startsWith(p))) return NextResponse.next(); - const session = readSessionCookie(request.headers.get("cookie")); + const session = await auth.getSession({ headers: request.headers }); if (!session) { const url = new URL("/login", request.url); `; export function DiffViewFull() { const [review, setReview] = React.useState<DiffReview>({ "src/auth/client.ts#0": "accepted", }); const decisions = Object.values(review); const accepted = decisions.filter((d) => d === "accepted").length; const rejected = decisions.length - accepted; return ( <div className="flex w-full max-w-3xl flex-col gap-3"> <DiffView title="Review changes" diff={AUTH_MIGRATION_DIFF} review={review} onReviewChange={setReview} maxHeight={620} /> <div className="flex items-center gap-3 px-1 text-[12px] text-kura-fg-subtle"> <span className="flex items-center gap-1.5"> <Kbd size="sm">J</Kbd> <Kbd size="sm">K</Kbd> <span>move</span> </span> <span className="flex items-center gap-1.5"> <Kbd size="sm">A</Kbd> <span>accept</span> </span> <span className="flex items-center gap-1.5"> <Kbd size="sm">R</Kbd> <span>reject</span> </span> <span className="flex items-center gap-1.5"> <Kbd size="sm">U</Kbd> <span>undo</span> </span> <span className="ml-auto font-kura-mono tabular-nums"> {accepted} accepted · {rejected} rejected </span> </div> </div> ); } ``` ### Structured files (variant) Rename, new file and a binary file from structured input; read-only. ```tsx import { type DiffFileInput, DiffView } from "@kura-ui/react/diff-view"; const STRUCTURED_FILES: DiffFileInput[] = [ { path: "src/auth/session-store.ts", oldPath: "src/auth/session.ts", status: "renamed", hunks: [ { oldStart: 3, newStart: 3, section: "export class SessionStore", lines: [ " #ttl = 15 * 60_000;", "- read(key: string) {", "+ read(key: string): Session | undefined {", " return this.#map.get(key);", ], }, ], }, { path: "src/auth/types.ts", status: "added", hunks: [ { newStart: 1, lines: [ '+export type { Session, User } from "@acme/auth";', "+", '+export type AuthProvider = "password" | "github" | "google";', ], }, ], }, { path: "public/og-login.png", status: "modified", binary: true, hunks: [] }, ]; export function DiffViewStructured() { return ( <DiffView title="Patch from test-writer" files={STRUCTURED_FILES} reviewable={false} className="w-full max-w-2xl" /> ); } ``` ### Apply accepted changes (composition) A footer bar with a Button acts on the accepted hunks. ```tsx "use client"; import * as React from "react"; import { Button } from "@kura-ui/react/button"; import { type DiffReview, DiffView } from "@kura-ui/react/diff-view"; const MIDDLEWARE_DIFF = `diff --git a/src/middleware.ts b/src/middleware.ts --- a/src/middleware.ts +++ b/src/middleware.ts @@ -1,4 +1,4 @@ import { NextResponse, type NextRequest } from "next/server"; -import { readSessionCookie } from "@/lib/legacy-session"; +import { auth } from "@/auth/client"; const PUBLIC_PATHS = ["/login", "/signup", "/api/health"]; @@ -8,5 +8,5 @@ export async function middleware(request: NextRequest) { if (PUBLIC_PATHS.some((p) => pathname.startsWith(p))) return NextResponse.next(); - const session = readSessionCookie(request.headers.get("cookie")); + const session = await auth.getSession({ headers: request.headers }); if (!session) { const url = new URL("/login", request.url); `; export function DiffViewComposition() { const [review, setReview] = React.useState<DiffReview>({}); const [applied, setApplied] = React.useState<number | null>(null); const accepted = Object.values(review).filter((d) => d === "accepted").length; return ( <div className="flex w-full max-w-3xl flex-col gap-3"> <DiffView title="kura/auth-client" diff={MIDDLEWARE_DIFF} review={review} onReviewChange={(next) => { setReview(next); setApplied(null); }} /> <div className="flex items-center justify-between gap-3 rounded-kura-xl bg-kura-surface py-2 pr-2 pl-3.5 shadow-kura-sm"> <span className="text-[13px] text-kura-fg-muted" role="status"> {applied != null ? `Applied ${applied} ${applied === 1 ? "change" : "changes"} to kura/auth-client` : accepted > 0 ? `${accepted} accepted ${accepted === 1 ? "change" : "changes"} ready` : "Accept changes to apply them"} </span> <Button size="sm" disabled={accepted === 0} onClick={() => setApplied(accepted)}> Apply changes </Button> </div> </div> ); } ``` ## Dependencies - npm: `lucide-react` - Kura registry items: `kura-theme`, `button`, `code-block`, `icon-button`, `tooltip`, `use-controllable-state`, `utils` - Related: `file-changes`, `code-block`, `terminal`, `approval-prompt`, `tool-call` --- # File Changes > The files an agent touched: a compact folder tree or flat list with A/M/D/R status, +/− counts, live “editing” markers and selection. - **Slug:** `file-changes` · **Category:** workspace · **Status:** experimental - **Import:** `import { FileChange, FileChangeStatus, FileChanges } from "@kura-ui/react/file-changes";` - **Docs:** https://kuro.abstergo.fyi/components/file-changes - **Registry item:** https://kuro.abstergo.fyi/r/file-changes.json - **Tags:** files, changes, git, tree, agent, status, sidebar, workspace ## Install ```bash # shadcn registry (copies source into your project) npx shadcn@latest add https://kuro.abstergo.fyi/r/file-changes.json # Kura CLI (same, plus dependency resolution and --json output) npx @kura-ui/cli add file-changes # npm package npm install @kura-ui/react ``` ## When to use - Show which files a coding agent has changed during or after a run (a sidebar next to the conversation or a diff). - Indicate live activity: which file the agent is reading or editing right now. - A file picker for a review screen: select a file to show its diff in diff-view. ## When not to use - Showing the actual line changes — use diff-view (pair them: FileChanges as navigation, DiffView as content). - A step-by-step log of the agent's actions — use agent-timeline or task-list. - A general file browser or editor tree with create/rename/drag — this is a read-only change list. ## Props | Prop | Type | Default | Required | Description | | --- | --- | --- | --- | --- | | `files` | `readonly FileChange[]` | — | yes | `{ path, status: "A" \| "M" \| "D" \| "R", oldPath?, additions?, deletions?, state?: "reading" \| "editing" }`. Paths are repo-relative with "/" separators. | | `title` | `React.ReactNode` | `"Changes"` | no | Header title. | | `view` | `"tree" \| "list"` | — | no | tree = folders (single-child chains compacted like VS Code, folders first); list = flat, file name then dimmed directory. Controlled. | | `defaultView` | `"tree" \| "list"` | `"tree"` | no | Initial view when uncontrolled. | | `onViewChange` | `(view: "tree" \| "list") => void` | — | no | Called when the header toggle switches views. | | `viewToggle` | `boolean` | `true` | no | Show the tree/list toggle in the header. | | `selectedPath` | `string \| null` | — | no | The selected file path (controlled). Pass null for no selection. | | `defaultSelectedPath` | `string \| null` | `null` | no | Initially selected file when uncontrolled. | | `onSelect` | `(path: string) => void` | — | no | Called when a file is chosen by click, Enter or Space. | | `defaultCollapsed` | `readonly string[]` | — | no | Folder paths collapsed initially, e.g. ["src/auth/__tests__"]. | | `maxHeight` | `number` | — | no | Scroll the rows inside this height (px). | | `actions` | `React.ReactNode` | — | no | Extra header controls. | | `empty` | `React.ReactNode` | — | no | Rendered when `files` is empty. Default an icon + “No changes yet”. | Native attributes of the root element, `className` and `ref` are passed through. ## Anatomy - **FileChanges** (`data-slot="file-changes"`) — `data-view="tree" | "list"`. - **Header** (`data-slot="file-changes-header"`) — Title, summary (`file-changes-summary`: “7 files +33 −38”), actions, view toggle. - **Rows** (`data-slot="file-changes-rows"`) — role="tree" (tree view) or role="listbox" (list view). - **Folder** (`data-slot="file-changes-folder"`) — treeitem with aria-expanded, `data-state="open" | "closed"`; collapsed folders show their file count and a pulsing dot if a file inside is being edited. - **File** (`data-slot="file-changes-file"`) — treeitem/option with aria-selected, `data-status="A" | "M" | "D" | "R"`, `data-state="reading" | "editing"`, `data-selected`. Selected rows get bg-kura-active and a 2px accent bar. - **Name** (`data-slot="file-changes-name"`) — Mono file name; shimmers while editing, struck through when deleted. - **Counts** (`data-slot="file-changes-counts"`) — +N −M in mono, or “editing” (accent, pulsing dot) / “reading”. - **Status** (`data-slot="file-changes-status"`) — Status letter: A green, M amber, D red, R muted; sr-only word (“, modified”). - **Guide** (`data-slot="file-changes-guide"`) — Hairline indent guides in the tree. ## Accessibility - Role: `tree | listbox` - Tree view is a WAI-ARIA tree (treeitems with aria-level/posinset/setsize, aria-expanded on folders, aria-selected on files); list view is a listbox of options. - One roving tab stop: Tab enters the list at the selected (or first) row. - Each file's accessible name includes its status word and live state (“client.ts … , modified, being edited”). - The view toggle buttons use aria-pressed and have tooltips. - Reduced motion: The editing pulse and name shimmer stop; row fade-in and chevron rotation are instant. | Keys | Action | | --- | --- | | ArrowDown / ArrowUp | Next / previous row | | ArrowRight | Expand a folder, or move into it | | ArrowLeft | Collapse a folder, or move to the parent folder | | Home / End | First / last row | | Enter / Space | Select a file, or toggle a folder | ## Notes for agents - Map git porcelain codes directly: A/M/D/R (treat C copies as A, T type changes as M). - Set `state: "editing"` on the file the agent is writing and clear it when done — the row shimmers and collapsed ancestor folders show a live dot. - Selection is single and files-only; folders toggle. Use onSelect to drive a DiffView or editor beside it. - Counts are optional; omit additions/deletions when unknown rather than passing 0. ## Examples ### Changed files (minimal) Seven files from the auth migration as a folder tree. ```tsx import { type FileChange, FileChanges } from "@kura-ui/react/file-changes"; const CHANGES: FileChange[] = [ { path: "src/auth/client.ts", status: "M", additions: 13, deletions: 16 }, { path: "src/auth/types.ts", status: "A", additions: 6 }, { path: "src/auth/__tests__/login.test.ts", status: "M", additions: 7, deletions: 5 }, { path: "src/middleware.ts", status: "M", additions: 2, deletions: 2 }, { path: "src/lib/legacy-session.ts", status: "D", deletions: 10 }, { path: "src/routes/account/page.tsx", status: "M", additions: 4, deletions: 4 }, { path: "package.json", status: "M", additions: 1, deletions: 1 }, ]; export function FileChangesMinimal() { return <FileChanges files={CHANGES} className="w-full max-w-sm" />; } ``` ### Live run (full) Files appear as the agent reads and edits them — the active one shimmers with an “editing” marker — then the run settles. Controlled selection. ```tsx "use client"; import * as React from "react"; import { type FileChange, FileChanges } from "@kura-ui/react/file-changes"; const STEPS: FileChange[][] = [ [{ path: "src/auth/client.ts", status: "M", state: "reading" }], [{ path: "src/auth/client.ts", status: "M", additions: 4, deletions: 6, state: "editing" }], [ { path: "src/auth/client.ts", status: "M", additions: 13, deletions: 16 }, { path: "src/middleware.ts", status: "M", additions: 1, deletions: 1, state: "editing" }, ], [ { path: "src/auth/client.ts", status: "M", additions: 13, deletions: 16 }, { path: "src/middleware.ts", status: "M", additions: 2, deletions: 2 }, { path: "src/auth/types.ts", status: "A", additions: 3, state: "editing" }, ], [ { path: "src/auth/client.ts", status: "M", additions: 13, deletions: 16 }, { path: "src/middleware.ts", status: "M", additions: 2, deletions: 2 }, { path: "src/auth/types.ts", status: "A", additions: 6 }, { path: "src/auth/__tests__/login.test.ts", status: "M", additions: 2, deletions: 3, state: "editing", }, ], [ { path: "src/auth/client.ts", status: "M", additions: 13, deletions: 16 }, { path: "src/middleware.ts", status: "M", additions: 2, deletions: 2 }, { path: "src/auth/types.ts", status: "A", additions: 6 }, { path: "src/auth/__tests__/login.test.ts", status: "M", additions: 7, deletions: 5 }, { path: "src/lib/legacy-session.ts", status: "D", deletions: 10 }, { path: "src/routes/account/page.tsx", status: "M", additions: 1, deletions: 1, state: "editing", }, ], CHANGES, ]; const CHANGES: FileChange[] = [ { path: "src/auth/client.ts", status: "M", additions: 13, deletions: 16 }, { path: "src/auth/types.ts", status: "A", additions: 6 }, { path: "src/auth/__tests__/login.test.ts", status: "M", additions: 7, deletions: 5 }, { path: "src/middleware.ts", status: "M", additions: 2, deletions: 2 }, { path: "src/lib/legacy-session.ts", status: "D", deletions: 10 }, { path: "src/routes/account/page.tsx", status: "M", additions: 4, deletions: 4 }, { path: "package.json", status: "M", additions: 1, deletions: 1 }, ]; export function FileChangesFull() { const [step, setStep] = React.useState(0); const [selected, setSelected] = React.useState<string | null>("src/auth/client.ts"); React.useEffect(() => { if (step >= STEPS.length - 1) return; const id = setTimeout(() => setStep((s) => s + 1), step === 0 ? 1400 : 1800); return () => clearTimeout(id); }, [step]); return ( <FileChanges title="Changes" files={STEPS[step]!} selectedPath={selected} onSelect={setSelected} className="w-full max-w-sm" /> ); } ``` ### Flat list (variant) List view: file name first, directory dimmed. ```tsx import { type FileChange, FileChanges } from "@kura-ui/react/file-changes"; const CHANGES: FileChange[] = [ { path: "src/auth/client.ts", status: "M", additions: 13, deletions: 16 }, { path: "src/auth/types.ts", status: "A", additions: 6 }, { path: "src/auth/__tests__/login.test.ts", status: "M", additions: 7, deletions: 5 }, { path: "src/middleware.ts", status: "M", additions: 2, deletions: 2 }, { path: "src/lib/legacy-session.ts", status: "D", deletions: 10 }, { path: "src/routes/account/page.tsx", status: "M", additions: 4, deletions: 4 }, { path: "package.json", status: "M", additions: 1, deletions: 1 }, ]; export function FileChangesList() { return ( <FileChanges files={CHANGES} defaultView="list" defaultSelectedPath="src/middleware.ts" className="w-full max-w-md" /> ); } ``` ### With DiffView (composition) FileChanges as navigation; DiffView shows the selected file parsed from the same unified diff. ```tsx "use client"; import * as React from "react"; import { DiffView, parseUnifiedDiff } from "@kura-ui/react/diff-view"; import { type FileChange, FileChanges } from "@kura-ui/react/file-changes"; const REVIEW_FILES = parseUnifiedDiff(AUTH_MIGRATION_DIFF); const AUTH_MIGRATION_DIFF = `diff --git a/src/auth/client.ts b/src/auth/client.ts index 887cccf..1c08d5a 100644 --- a/src/auth/client.ts +++ b/src/auth/client.ts @@ -1,7 +1,8 @@ import { cache } from "react"; -import { fetchJson } from "@/lib/http"; -import type { Session, User } from "./types"; +import { createAuthClient, type Session, type User } from "@acme/auth"; -const SESSION_URL = "/api/v1/session"; -const REFRESH_URL = "/api/v1/session/refresh"; +export const auth = createAuthClient({ + baseUrl: process.env.NEXT_PUBLIC_AUTH_URL, + refresh: "auto", +}); @@ -9,14 +10,10 @@ const REFRESH_URL = "/api/v1/session/refresh"; export const fetchUser = cache(async (): Promise<User | null> => { - const res = await fetchJson<Session>(SESSION_URL, { credentials: "include" }); - if (!res.ok) return null; - return res.data.user; + const session = await auth.getSession(); + return session?.user ?? null; }); -export async function refreshSession(token: string): Promise<Session> { - const res = await fetchJson<Session>(REFRESH_URL, { - method: "POST", - body: JSON.stringify({ token }), - }); - if (!res.ok) throw new Error(\`refresh failed: \${res.status}\`); - return res.data; +export async function refreshSession(session: Session): Promise<Session> { + const next = await auth.refresh(session.refreshToken); + if (!next) throw new Error("refresh failed: session revoked"); + return next; } @@ -24,3 +21,3 @@ export async function refreshSession(token: string): Promise<Session> { export function isExpired(session: Session, now = Date.now()): boolean { - return session.expiresAt < now; + return session.expiresAt <= now; } @@ -28,3 +25,3 @@ export function isExpired(session: Session, now = Date.now()): boolean { export async function signOut(): Promise<void> { - await fetchJson(SESSION_URL, { method: "DELETE", credentials: "include" }); + await auth.signOut(); } diff --git a/src/auth/__tests__/login.test.ts b/src/auth/__tests__/login.test.ts index 9fe0aaf..711a4bd 100644 --- a/src/auth/__tests__/login.test.ts +++ b/src/auth/__tests__/login.test.ts @@ -1,4 +1,4 @@ import { describe, expect, it, vi } from "vitest"; -import { refreshSession, isExpired } from "../client"; +import { auth, isExpired, refreshSession } from "../client"; describe("login", () => { @@ -8,8 +8,10 @@ describe("login", () => { it("refreshes an expired session", async () => { - vi.spyOn(globalThis, "fetch").mockResolvedValue( - new Response(JSON.stringify({ expiresAt: 10, user: { id: "u_1" } })), - ); - const next = await refreshSession("tok_expired"); + vi.spyOn(auth, "refresh").mockResolvedValue({ + expiresAt: 10, + refreshToken: "tok_next", + user: { id: "u_1" }, + } as never); + const next = await refreshSession({ refreshToken: "tok_expired" } as never); expect(next.user.id).toBe("u_1"); }); diff --git a/src/lib/legacy-session.ts b/src/lib/legacy-session.ts deleted file mode 100644 index f0ae86d..0000000 --- a/src/lib/legacy-session.ts +++ /dev/null @@ -1,10 +0,0 @@ -/** @deprecated Use \`auth.getSession()\` from @acme/auth. */ -export function readSessionCookie(cookie: string | null) { - const raw = cookie?.match(/acme_session=([^;]+)/)?.[1]; - if (!raw) return null; - try { - return JSON.parse(atob(raw)) as { userId: string; expiresAt: number }; - } catch { - return null; - } -} diff --git a/src/middleware.ts b/src/middleware.ts index 0e93409..7eda2e2 100644 --- a/src/middleware.ts +++ b/src/middleware.ts @@ -1,4 +1,4 @@ import { NextResponse, type NextRequest } from "next/server"; -import { readSessionCookie } from "@/lib/legacy-session"; +import { auth } from "@/auth/client"; const PUBLIC_PATHS = ["/login", "/signup", "/api/health"]; @@ -8,5 +8,5 @@ export async function middleware(request: NextRequest) { if (PUBLIC_PATHS.some((p) => pathname.startsWith(p))) return NextResponse.next(); - const session = readSessionCookie(request.headers.get("cookie")); + const session = await auth.getSession({ headers: request.headers }); if (!session) { const url = new URL("/login", request.url); `; export function FileChangesComposition() { const [selected, setSelected] = React.useState("src/auth/client.ts"); const files: FileChange[] = REVIEW_FILES.map((f) => { const lines = f.hunks.flatMap((h) => h.lines); return { path: f.path, status: f.status === "added" ? "A" : f.status === "deleted" ? "D" : f.status === "renamed" ? "R" : "M", additions: lines.filter((l) => l.kind === "add").length, deletions: lines.filter((l) => l.kind === "remove").length, }; }); const current = REVIEW_FILES.filter((f) => f.path === selected); return ( <div className="grid w-full max-w-4xl items-start gap-3 md:grid-cols-[17rem_1fr]"> <FileChanges files={files} selectedPath={selected} onSelect={setSelected} viewToggle={false} /> <DiffView title={selected.split("/").pop()} files={current} reviewable={false} wrap /> </div> ); } ``` ## Dependencies - npm: `lucide-react` - Kura registry items: `kura-theme`, `icon-button`, `shimmer-text`, `use-controllable-state`, `utils` - Related: `diff-view`, `terminal`, `agent-timeline`, `task-list`, `run-header` --- # 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, Copy, Download, Mic, Paperclip, Pin, Plus, RotateCcw, Share, Trash2 } from "lucide-react"; import { IconButton } from "@kura-ui/react/icon-button"; export function IconButtonFull() { return ( <div className="flex flex-col items-center gap-4"> <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 aria-hidden 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" /> </div> <div className="flex items-center gap-2"> <IconButton label="Copy" icon={<Copy />} /> <IconButton label="Download" icon={<Download />} variant="secondary" /> <IconButton label="Share" icon={<Share />} variant="outline" /> <IconButton label="New chat" icon={<Plus />} variant="primary" shortcut={["mod", "shift", "o"]} /> <IconButton label="Delete" icon={<Trash2 />} variant="outline" disabled /> <IconButton label="Pin" icon={<Pin />} size="xs" tooltip={false} /> </div> </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 flex-wrap items-center justify-center gap-x-5 gap-y-2 text-[13px]"> <span className="flex items-center gap-2"> Run task <Kbd keys={["mod", "shift", "p"]} size="sm" /> </span> <span className="flex items-center gap-2"> Insert line <Kbd keys={["alt", "enter"]} variant="ghost" /> </span> <span className="flex items-center gap-2"> Edit last <Kbd keys={["up"]} pressed /> </span> </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:** primitives · **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` --- # 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 bubble (a translucent fg tint that separates from any surface, in both themes); 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" 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` --- # Popover > Floating panel (opaque raised surface, hairline ring, soft shadow) 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 { Gauge } from "lucide-react"; 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="outline"> <Gauge /> Usage </Button> </PopoverTrigger> <PopoverContent aria-labelledby="usage-title" className="w-64"> <div className="flex flex-col gap-2.5"> <div className="flex items-baseline justify-between"> <h3 id="usage-title" className="font-medium text-sm"> Weekly usage </h3> <span className="text-kura-fg-muted text-xs tabular-nums">38 / 50</span> </div> <div className="h-1.5 overflow-hidden rounded-full bg-kura-gray-4"> <div className="h-full w-[76%] rounded-full bg-kura-ink" /> </div> <p className="text-kura-fg-muted text-xs leading-relaxed"> Opus messages reset on Monday at 09:00. Haiku is unlimited. </p> </div> </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"; const efforts = ["Low", "Medium", "High"] as const; export function PopoverFull() { const [open, setOpen] = React.useState(false); const [effort, setEffort] = React.useState<(typeof efforts)[number]>("Medium"); const [temperature, setTemperature] = React.useState(0.7); return ( <Popover open={open} onOpenChange={setOpen}> <PopoverTrigger asChild> <Button variant="outline"> <Settings2 /> Generation settings </Button> </PopoverTrigger> <PopoverContent side="bottom" align="start" aria-labelledby="gen-settings-title" className="w-72 p-0" > <div className="flex flex-col gap-4 p-4"> <div className="flex flex-col gap-0.5"> <h3 id="gen-settings-title" className="font-medium text-sm"> Generation </h3> <p className="text-kura-fg-muted text-xs">Applies to new replies in this chat.</p> </div> <fieldset className="flex flex-col"> <legend className="mb-2 font-medium text-kura-fg-muted text-xs"> Reasoning effort </legend> <div className="grid grid-cols-3 gap-0.5 rounded-kura-md bg-kura-surface-sunken p-0.5 shadow-[inset_0_0_0_1px_var(--kura-border-subtle)]"> {efforts.map((option) => ( <label key={option} className="flex h-7 cursor-pointer items-center justify-center rounded-kura-sm font-medium text-kura-fg-muted text-xs transition-[background-color,color,box-shadow] duration-(--kura-duration-fast) ease-kura-out hover:text-kura-fg has-checked:bg-kura-surface-raised has-checked:text-kura-fg has-checked:shadow-kura-sm has-focus-visible:shadow-kura-focus" > <input type="radio" name="reasoning-effort" value={option} checked={effort === option} onChange={() => setEffort(option)} className="sr-only" /> {option} </label> ))} </div> </fieldset> <label className="flex flex-col gap-2"> <span className="flex items-center justify-between font-medium text-kura-fg-muted text-xs"> Temperature <span className="font-kura-mono text-kura-fg tabular-nums"> {temperature.toFixed(1)} </span> </span> <input type="range" min={0} max={1} step={0.1} value={temperature} onChange={(e) => setTemperature(Number(e.target.value))} className="h-4 w-full cursor-pointer accent-kura-ink" /> <span className="flex justify-between text-[11px] text-kura-fg-subtle"> <span>Precise</span> <span>Creative</span> </span> </label> </div> <div className="flex items-center justify-end gap-2 border-kura-border-subtle border-t px-4 py-3"> <Button variant="ghost" size="sm" onClick={() => { setEffort("Medium"); setTemperature(0.7); }} > Reset </Button> <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 Queue > Stack of follow-up prompts queued while an agent works: reorder, edit inline, remove, or Send now to steer. Renders nothing when empty. - **Slug:** `prompt-queue` · **Category:** agent · **Status:** experimental - **Import:** `import { PromptQueue, QueuedPrompt, QueuedPromptAttachment } from "@kura-ui/react/prompt-queue";` - **Docs:** https://kuro.abstergo.fyi/components/prompt-queue - **Registry item:** https://kuro.abstergo.fyi/r/prompt-queue.json - **Tags:** agent, queue, prompts, follow-up, steer, reorder, drag, composer ## Install ```bash # shadcn registry (copies source into your project) npx shadcn@latest add https://kuro.abstergo.fyi/r/prompt-queue.json # Kura CLI (same, plus dependency resolution and --json output) npx @kura-ui/cli add prompt-queue # npm package npm install @kura-ui/react ``` ## When to use - The user types follow-ups while an agent is mid-turn (Claude Code / Codex queued messages) and they should send in order when it finishes. - Letting the user steer: interrupt the agent and send one queued prompt immediately. - Directly above a composer (variant='tray') so queued prompts read as part of the input. ## When not to use - Suggested prompts the user has not written — use prompt-suggestions. - The prompt input itself — use composer (and put PromptQueue above it). - Work the agent plans to do — use task-list. ## Props | Prop | Type | Default | Required | Description | | --- | --- | --- | --- | --- | | `items` | `QueuedPrompt[]` | — | no | Queued prompts in send order (controlled): { id, text, attachments?: { name, type?: 'image' \| 'file' }[] }. | | `defaultItems` | `QueuedPrompt[]` | — | no | Initial prompts when uncontrolled. | | `onItemsChange` | `(items: QueuedPrompt[]) => void` | — | no | Called with the whole new list after a reorder, edit, remove or Send now. Fires on every step while dragging. | | `onSendNow` | `(item: QueuedPrompt) => void` | — | no | Steer: interrupt the agent and send this prompt now. The prompt is removed from the queue first. Without it no Send now button renders. | | `title` | `React.ReactNode` | `"Queued"` | no | Header title; the count follows it. | | `hint` | `React.ReactNode` | `"Sends when the agent finishes this turn"` | no | Secondary header text, e.g. 'Sends when Kura finishes running pnpm test'. null hides it. | | `variant` | `"panel" \| "tray"` | `"panel"` | no | panel = standalone card; tray = sunken, rounded on top only, meant to sit flush on top of a Composer (inset it with className='mx-3'). | Native attributes of the root element, `className` and `ref` are passed through. ## Anatomy - **PromptQueue** (`data-slot="prompt-queue"`) — Root with `data-variant`. - **Header** (`data-slot="prompt-queue-header"`) — Title, count and prompt-queue-hint. - **Item** (`data-slot="prompt-queue-item"`) — Focusable <li> (`data-state` = editing | dragging): index (grip on hover), text, attachments, actions. - **Handle** (`data-slot="prompt-queue-handle"`) — Drag grip shown in place of the index on hover (pointer only; keyboard uses Alt+arrows or Space). - **Text** (`data-slot="prompt-queue-text"`) — One truncated line; the full text is the title tooltip. - **Attachments** (`data-slot="prompt-queue-attachments"`) — First attachment's icon and name in mono, then '+N'. - **Actions** (`data-slot="prompt-queue-actions"`) — Move up, Move down, Edit, Remove and prompt-queue-send ('Send now'); shown on hover/focus, always on touch. - **Editor** (`data-slot="prompt-queue-editor"`) — Auto-growing textarea replacing the row while editing, with Cancel/Save. ## Accessibility - Role: `list (ol) of focusable items` - The list is labelled by the title and described by visually hidden keyboard help. Items use a roving tabindex (one Tab stop) and are named '2 of 3: <text>'. - A polite status region announces moves ('Moved to position 1 of 3'), removals and Send now. Actions are icon buttons with tooltips. - Escape in the editor cancels without reaching the composer's own Escape (stop) handler. - Reduced motion: Reorders jump into place instead of sliding; the drag still follows the pointer. | Keys | Action | | --- | --- | | ArrowUp / ArrowDown | Move focus between prompts | | Alt+ArrowUp / Alt+ArrowDown | Move the focused prompt up / down | | Space, then arrows, then Space | Grab, move and drop (Escape restores) | | Enter / F2 | Edit inline (Enter saves, Shift+Enter newline, Escape cancels) | | Delete / Backspace | Remove | | Mod+Enter | Send now | ## Notes for agents - When the agent finishes a turn, shift the first item off `items` and send it yourself — the component never sends on its own. - onSendNow means 'interrupt and send': stop the current turn in your harness before sending. - Keep ids stable across edits; reordering and focus rely on them. - Empty queue renders only a visually hidden status region, so you can leave it mounted above the composer. ## Examples ### Two queued prompts (minimal) ```tsx "use client"; import { PromptQueue } from "@kura-ui/react/prompt-queue"; export function PromptQueueMinimal() { return ( <PromptQueue className="w-full max-w-xl" defaultItems={[ { id: "readme", text: "When tests pass, update the auth section of the README" }, { id: "legacy", text: "Don't touch src/legacy/ — it's deleted next sprint" }, ]} onSendNow={() => {}} /> ); } ``` ### Controlled, with steering (full) Attachments, a prompt that arrives after mount, and Send now reported below. ```tsx "use client"; import { CornerDownRight } from "lucide-react"; import * as React from "react"; import { PromptQueue, type QueuedPrompt } from "@kura-ui/react/prompt-queue"; const QUEUE: QueuedPrompt[] = [ { id: "helper", text: "Use the refreshSession() helper instead of calling fetch('/api/session') directly", attachments: [{ name: "session-flow.png", type: "image" }], }, { id: "legacy", text: "Don't touch src/legacy/ — it's being deleted next sprint", }, { id: "readme", text: "When tests pass, update the auth section of the README and link the migration guide", attachments: [ { name: "MIGRATION.md", type: "file" }, { name: "auth-diagram.png", type: "image" }, ], }, ]; export function PromptQueueFull() { const [items, setItems] = React.useState<QueuedPrompt[]>(QUEUE); const [steered, setSteered] = React.useState<string | null>(null); // A teammate queues one more follow-up a moment after mount. React.useEffect(() => { const t = setTimeout( () => setItems((list) => list.some((i) => i.id === "pr") ? list : [...list, { id: "pr", text: "Open the PR as a draft and request review from @maya" }], ), 1600, ); return () => clearTimeout(t); }, []); return ( <div className="flex w-full max-w-xl flex-col gap-2"> <PromptQueue items={items} onItemsChange={setItems} onSendNow={(item) => setSteered(item.text)} hint="Sends when Kura finishes running pnpm test" /> <p className="flex min-h-5 items-center gap-1.5 px-1 text-[12px] text-kura-fg-subtle" aria-live="polite" > {steered ? ( <> <CornerDownRight aria-hidden className="size-3.5 shrink-0" strokeWidth={1.75} /> <span className="truncate"> Interrupted Kura and sent: <span className="text-kura-fg-muted">{steered}</span> </span> </> ) : ( "Hover a prompt, or focus it and use Alt+↑/↓, Enter, Delete and ⌘↵." )} </p> </div> ); } ``` ### Tray (variant) Rounded on top only, tucked onto the input below. ```tsx "use client"; import { PromptQueue, type QueuedPrompt } from "@kura-ui/react/prompt-queue"; const QUEUE: QueuedPrompt[] = [ { id: "helper", text: "Use the refreshSession() helper instead of calling fetch('/api/session') directly", attachments: [{ name: "session-flow.png", type: "image" }], }, { id: "legacy", text: "Don't touch src/legacy/ — it's being deleted next sprint", }, { id: "readme", text: "When tests pass, update the auth section of the README and link the migration guide", attachments: [ { name: "MIGRATION.md", type: "file" }, { name: "auth-diagram.png", type: "image" }, ], }, ]; export function PromptQueueTray() { return ( <div className="flex w-full max-w-xl flex-col"> <PromptQueue variant="tray" className="mx-3" defaultItems={QUEUE.slice(0, 2)} onSendNow={() => {}} /> <div className="h-16 rounded-kura-xl bg-kura-surface shadow-kura-sm" /> </div> ); } ``` ### Above a composer (composition) Messages sent while the agent works are queued; Send now steers. ```tsx "use client"; import { CornerDownRight } from "lucide-react"; import * as React from "react"; import { Composer } from "@kura-ui/react/composer"; import { RunHeader } from "@kura-ui/react/run-header"; import { PromptQueue, type QueuedPrompt } from "@kura-ui/react/prompt-queue"; const QUEUE: QueuedPrompt[] = [ { id: "helper", text: "Use the refreshSession() helper instead of calling fetch('/api/session') directly", attachments: [{ name: "session-flow.png", type: "image" }], }, { id: "legacy", text: "Don't touch src/legacy/ — it's being deleted next sprint", }, { id: "readme", text: "When tests pass, update the auth section of the README and link the migration guide", attachments: [ { name: "MIGRATION.md", type: "file" }, { name: "auth-diagram.png", type: "image" }, ], }, ]; export function PromptQueueComposition() { const [items, setItems] = React.useState<QueuedPrompt[]>(QUEUE.slice(0, 2)); const [log, setLog] = React.useState<string[]>([]); const [startedAt] = React.useState(() => Date.now() - 611_000); return ( <div className="flex w-full max-w-xl flex-col gap-3"> <RunHeader variant="bar" title="Run pnpm test --filter web" status="running" startedAt={startedAt} progress={{ done: 5, total: 7 }} cost={1.52} onStop={() => {}} shortcuts={false} /> {log.length > 0 && ( <ul className="flex flex-col gap-1 px-1 text-[12px] text-kura-fg-subtle"> {log.map((l, i) => ( <li key={i} className="flex items-center gap-1.5 truncate"> <CornerDownRight aria-hidden className="size-3.5 shrink-0" strokeWidth={1.75} /> Steered: <span className="truncate text-kura-fg-muted">{l}</span> </li> ))} </ul> )} <div className="flex flex-col"> <PromptQueue variant="tray" className="mx-3" items={items} onItemsChange={setItems} onSendNow={(item) => setLog((l) => [...l, item.text])} hint="Sends after this turn" /> <Composer className="relative" placeholder="Queue a follow-up for Kura…" onSubmit={(m) => setItems((list) => [...list, { id: `q-${Date.now()}`, text: m.text }])} /> </div> </div> ); } ``` ## Dependencies - npm: `lucide-react`, `motion` - Kura registry items: `kura-theme`, `button`, `icon-button`, `kura-motion`, `use-controllable-state`, `use-reduced-motion`, `utils` - Related: `composer`, `run-header`, `prompt-suggestions`, `task-list` --- # 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-3 text-[15px] text-kura-fg leading-relaxed"> <Reasoning key={run} active={active} open={open} onOpenChange={setOpen} autoCollapse className="w-full" > <StreamingText stream={stream} caret={false} onComplete={() => setActive(false)} /> </Reasoning> {!active && ( <div className="flex animate-kura-fade-in flex-col items-start gap-3"> <p> Wrap the click in a transition and render from{" "} <code className="rounded-kura-xs bg-kura-active px-[0.3em] py-[0.1em] font-kura-mono text-[0.86em]"> useOptimistic </code> . The count updates on the same frame, and if the server action throws, React drops the optimistic value and the real count comes back on its own. </p> <Button variant="ghost" size="xs" className="-ml-2 text-kura-fg-muted" onClick={replay}> <RotateCcw /> Think again </Button> </div> )} </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` --- # Run Header > Header for one agent run: title, agent, model, branch, status, live elapsed clock, tokens, cost vs budget, step progress and Stop/Pause controls. - **Slug:** `run-header` · **Category:** agent · **Status:** experimental - **Import:** `import { RunHeader, RunHeaderProgress, RunHeaderTokens } from "@kura-ui/react/run-header";` - **Docs:** https://kuro.abstergo.fyi/components/run-header - **Registry item:** https://kuro.abstergo.fyi/r/run-header.json - **Tags:** agent, run, session, header, status, cost, budget, tokens, timer, stop ## Install ```bash # shadcn registry (copies source into your project) npx shadcn@latest add https://kuro.abstergo.fyi/r/run-header.json # Kura CLI (same, plus dependency resolution and --json output) npx @kura-ui/cli add run-header # npm package npm install @kura-ui/react ``` ## When to use - The top of a page or pane that shows one agent session (Claude Code, Codex, Devin-style runs): what it is doing, how long, how much it costs, and a way to stop it. - A dense status row above a run's transcript, plan or fleet (variant='bar'). - Showing spend against a per-run budget, with the meter turning amber at 80% and red past 100%. - Giving the human Stop / Pause / Resume with keyboard shortcuts while an agent works. ## When not to use - The run's step-by-step plan — use task-list (todo-style) or agent-timeline (steps with connectors). - Parallel subagents inside a run — use agent-fleet. - Context-window usage of one conversation — use context-meter. - A single tool invocation — use tool-call. ## Props | Prop | Type | Default | Required | Description | | --- | --- | --- | --- | --- | | `title` | `React.ReactNode` | — | yes | What the run is doing, e.g. "Migrate session API to @acme/auth". Truncates. | | `agent` | `string` | — | no | Agent name, e.g. "Kura". Panel meta line only. | | `model` | `string` | — | no | Model id in mono, e.g. "claude-opus-5-5". Panel meta line only. | | `status` | `"queued" \| "running" \| "waiting" \| "done" \| "failed" \| "skipped" \| "paused"` | — | yes | Run state, drawn with StatusGlyph. running = blue arc + shimmering 'Running'; waiting = amber 'Waiting for you'; done = 'Completed'; failed = red; skipped = 'Stopped'. queued/running/waiting/paused keep the clock ticking. | | `startedAt` | `Date \| number` | — | no | Run start. Drives the live elapsed clock (m:ss, h:mm:ss). Without it the clock shows –:––. | | `endedAt` | `Date \| number` | — | no | Run end. Freezes the clock at endedAt − startedAt (use for finished or persisted runs). | | `tokens` | `{ input: number; output: number }` | — | no | Token usage. Panel shows "412k in · 38.1k out"; bar shows the total. | | `cost` | `number` | — | no | Spend so far in USD, formatted $1.82. | | `budget` | `number` | — | no | Budget in USD. Shows '$1.82 of $5.00' with a 4px meter; amber from 80%, red (and red cost) past 100%. | | `branch` | `string` | — | no | Git branch in mono with a branch icon. In the bar it shows from ~768px container width. | | `progress` | `{ done: number; total: number }` | — | no | Plan progress: '4 of 7' plus a segmented bar (continuous above 24 steps). The current segment is blue while running, amber while waiting, red when failed. | | `actions` | `React.ReactNode` | — | no | Extra controls before Pause/Stop, e.g. an 'Open PR' Button once the run is done. | | `onStop` | `() => void` | — | no | Shows Stop while the run is live (queued, running, waiting, paused). Bound to ⌘/Ctrl+. | | `onPause` | `() => void` | — | no | Shows Pause while running. Bound to ⌘/Ctrl+Shift+P. | | `onResume` | `() => void` | — | no | Shows Resume while paused. Bound to ⌘/Ctrl+Shift+P. | | `variant` | `"bar" \| "panel"` | `"panel"` | no | bar = one 44px row (glyph, title, status, branch, steps, tokens, cost, clock, controls; stats drop out as the container narrows). panel = title + meta line + a stats strip (Elapsed, Steps, Tokens, Spend). | | `shortcuts` | `boolean` | `true` | no | Bind ⌘/Ctrl+. (Stop) and ⌘/Ctrl+Shift+P (Pause/Resume) on the document. Only one run header on screen should bind them. | Native attributes of the root element, `className` and `ref` are passed through. ## Anatomy - **RunHeader** (`data-slot="run-header"`) — Root <section> labelled by the title; `data-variant`, `data-status`. A size container. - **Title** (`data-slot="run-header-title"`) — <h2>, truncated. - **Status** (`data-slot="run-header-status"`) — Status word; shimmers while running, amber when waiting, red when failed. - **Agent** (`data-slot="run-header-agent"`) — Agent name (panel). - **Model** (`data-slot="run-header-model"`) — Model id in mono (panel). - **Branch** (`data-slot="run-header-branch"`) — Branch icon + mono name. - **Controls** (`data-slot="run-header-controls"`) — actions, then run-header-pause and run-header-stop. - **Stats** (`data-slot="run-header-stats"`) — <dl>. In the panel each cell is run-header-stat with `data-stat` = elapsed | steps | tokens | cost, separated by hairlines. - **Elapsed** (`data-slot="run-header-elapsed"`) — Mono tabular clock with reserved width so ticking never shifts layout. ## Accessibility - Role: `region (section labelled by the title)` - The stats are a <dl>: each value has a term (Elapsed, Steps, Tokens, Spend), visually hidden in the bar. - A polite status region announces only status changes ('Run waiting for you'); the ticking clock and counters are not announced. - Stop and Pause have tooltips with their shortcuts and aria-keyshortcuts. Status is never colour-only: the glyph shape and the status word carry it. - The status glyph is decorative here (label=null) because the status word sits next to it. - Reduced motion: The running arc, the current step's pulse and the status shimmer stop; meters change width without transition. | Keys | Action | | --- | --- | | Mod+. | Stop the run (when onStop is set and the run is live) | | Mod+Shift+P | Pause or resume | | Tab | Actions, Pause, Stop | ## Notes for agents - Keep one RunHeader mounted for the life of a run and update props; pass startedAt from the server so reloads keep the right clock, and endedAt once it finishes. - Set shortcuts={false} on every RunHeader except the one for the focused run, otherwise ⌘. stops all of them. - Map harness states: in-progress → running; needs approval / input → waiting; interrupted by the user → skipped ('Stopped'); error → failed. - tokens.input should include cache reads if you want the number to match the bill; cost is whatever you computed — the component only formats it. - Use the bar inside dense layouts (above a fleet or transcript) and the panel at the top of a run page. ## Examples ### Running (minimal) Title, agent, model, status and a live clock. ```tsx "use client"; import * as React from "react"; import { RunHeader } from "@kura-ui/react/run-header"; const minutesAgo = (m: number) => Date.now() - m * 60_000; export function RunHeaderMinimal() { const [startedAt] = React.useState(() => minutesAgo(3.2)); return ( <RunHeader className="w-full max-w-2xl" title="Migrate session API to @acme/auth" agent="Kura" model="claude-opus-5-5" status="running" startedAt={startedAt} shortcuts={false} /> ); } ``` ### Live run (full) Steps advance, tokens and spend climb against a $5 budget, the run waits for approval, then completes and offers Open PR. Pause, Resume and Stop work (⌘. and ⌘⇧P). ```tsx "use client"; import { GitPullRequestArrow } from "lucide-react"; import * as React from "react"; import { Button } from "@kura-ui/react/button"; import type { AgentStatus } from "@kura-ui/react/status-glyph"; import { RunHeader } from "@kura-ui/react/run-header"; const minutesAgo = (m: number) => Date.now() - m * 60_000; const SCRIPT: { status: AgentStatus; done: number; input: number; output: number; ms: number }[] = [ { status: "running", done: 4, input: 268_400, output: 21_900, ms: 1800 }, { status: "running", done: 4, input: 297_100, output: 24_300, ms: 1600 }, { status: "waiting", done: 4, input: 301_800, output: 25_000, ms: 2600 }, { status: "running", done: 5, input: 338_200, output: 29_400, ms: 1800 }, { status: "running", done: 6, input: 376_900, output: 33_800, ms: 2000 }, { status: "running", done: 7, input: 412_300, output: 38_100, ms: 1400 }, { status: "done", done: 7, input: 412_300, output: 38_100, ms: 0 }, ]; const priceOf = (input: number, output: number) => (input * 2.5 + output * 20) / 1_000_000 + 0.03; export function RunHeaderFull() { const [startedAt] = React.useState(() => minutesAgo(11.4)); const [beat, setBeat] = React.useState(0); const [override, setOverride] = React.useState<AgentStatus | null>(null); const [endedAt, setEndedAt] = React.useState<number | undefined>(); const step = SCRIPT[Math.min(beat, SCRIPT.length - 1)] as (typeof SCRIPT)[number]; const status = override ?? step.status; // biome-ignore lint/correctness/useExhaustiveDependencies: re-arm the timer on every beat React.useEffect(() => { if (override != null || step.ms === 0) return; const t = setTimeout(() => setBeat((b) => Math.min(b + 1, SCRIPT.length - 1)), step.ms); return () => clearTimeout(t); }, [beat, override, step.ms]); React.useEffect(() => { if ((status === "done" || status === "skipped") && endedAt == null) setEndedAt(Date.now()); }, [status, endedAt]); return ( <RunHeader className="w-full max-w-3xl" title="Migrate session API to @acme/auth" agent="Kura" model="claude-opus-5-5" branch="kura/auth-client" status={status} startedAt={startedAt} endedAt={endedAt} progress={{ done: step.done, total: 7 }} tokens={{ input: step.input, output: step.output }} cost={priceOf(step.input, step.output)} budget={5} onPause={() => setOverride("paused")} onResume={() => setOverride(null)} onStop={() => setOverride("skipped")} actions={ status === "done" ? ( <Button size="sm" variant="primary" className="animate-kura-fade-in"> <GitPullRequestArrow /> Open PR </Button> ) : null } /> ); } ``` ### Bar (variant) One dense row per run: running, waiting for you, failed and completed. ```tsx "use client"; import * as React from "react"; import { RunHeader } from "@kura-ui/react/run-header"; export function RunHeaderBar() { const [t] = React.useState(() => Date.now()); return ( <div className="flex w-full max-w-3xl flex-col gap-2"> <RunHeader variant="bar" title="Migrate session API to @acme/auth" status="running" branch="kura/auth-client" startedAt={t - 8 * 60_000 - 42_000} progress={{ done: 4, total: 7 }} tokens={{ input: 268_400, output: 21_900 }} cost={1.12} budget={5} onPause={() => {}} onStop={() => {}} shortcuts={false} /> <RunHeader variant="bar" title="Patch src/middleware.ts" status="waiting" branch="kura/auth-client" startedAt={t - 9 * 60_000 - 5_000} progress={{ done: 4, total: 7 }} tokens={{ input: 301_800, output: 25_000 }} cost={1.31} budget={5} onStop={() => {}} shortcuts={false} /> <RunHeader variant="bar" title="Fix login.test.ts › refreshes an expired session" status="failed" branch="kura/auth-client" startedAt={t - 14 * 60_000} endedAt={t - 2 * 60_000 - 51_000} progress={{ done: 5, total: 7 }} tokens={{ input: 356_000, output: 31_200 }} cost={1.58} budget={5} /> <RunHeader variant="bar" title="Bump @acme/auth to 2.4.0" status="done" branch="kura/auth-client" startedAt={t - 31 * 60_000} endedAt={t - 19 * 60_000 - 6_000} progress={{ done: 7, total: 7 }} tokens={{ input: 412_300, output: 38_100 }} cost={1.82} budget={5} /> </div> ); } ``` ### With agent-fleet (composition) A bar header above the run's subagents. ```tsx "use client"; import * as React from "react"; import { AgentFleet, type FleetAgent } from "@kura-ui/react/agent-fleet"; import { RunHeader } from "@kura-ui/react/run-header"; const minutesAgo = (m: number) => Date.now() - m * 60_000; const FLEET: FleetAgent[] = [ { id: "explorer", name: "explorer", role: "Maps call sites", status: "done", activity: "Found 23 calls to fetchUser() in 9 files", startedAt: minutesAgo(9), endedAt: minutesAgo(7.4), tokens: 84_200, cost: 0.21, }, { id: "test-writer", name: "test-writer", role: "Updates tests", status: "running", activity: "Rewriting mocks in src/auth/__tests__/login.test.ts", progress: 0.62, startedAt: minutesAgo(3.1), tokens: 51_600, cost: 0.14, }, { id: "reviewer", name: "reviewer", role: "Reviews the diff", status: "queued", activity: "Starts after test-writer", }, ]; export function RunHeaderComposition() { const [startedAt] = React.useState(() => minutesAgo(9.6)); return ( <div className="flex w-full max-w-3xl flex-col gap-2"> <RunHeader variant="bar" title="Migrate session API to @acme/auth" status="running" branch="kura/auth-client" startedAt={startedAt} progress={{ done: 5, total: 7 }} tokens={{ input: 338_200, output: 29_400 }} cost={1.46} budget={5} onPause={() => {}} onStop={() => {}} shortcuts={false} /> <AgentFleet agents={FLEET} density="compact" defaultSelectedId="test-writer" onSelect={() => {}} /> </div> ); } ``` ## Dependencies - npm: `lucide-react` - Kura registry items: `kura-theme`, `button`, `icon-button`, `kura-format`, `shimmer-text`, `status-glyph`, `tooltip`, `use-elapsed`, `use-hotkey`, `utils` - Related: `agent-fleet`, `task-list`, `checkpoints`, `context-meter`, `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:** primitives · **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 a GPU visual inside a component, such as the agent orb. - A custom decorative shader behind a hero, card or voice surface. ## When not to use - A voice-agent sphere — use agent-orb. - 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 sunken neutral surface with one soft accent-subtle wash (tokens, follows the theme; `data-slot="shader-canvas-fallback"`). | | `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. - **DefaultFallback** (`data-slot="shader-canvas-fallback"`) — Rendered only when WebGL2 fails and no `fallback` is passed: a neutral token gradient with a soft accent wash. ## 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.125, 0.425, 0.905); // Kura blue, sRGB vec3 b = vec3(0.054, 0.061, 0.071); // graphite float t = 0.5 + 0.5 * sin(u_time * 0.5 + uv.x * 2.2 + uv.y * 1.4); fragColor = vec4(mix(a, b, smoothstep(0.0, 1.0, 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 < 3; 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) * 1.4; 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.25, 0.75, f)); col = mix(col, u_colorC, 0.6 * smoothstep(0.75, 1.05, length(q))); col += 0.012 * (hash(gl_FragCoord.xy) - 0.5); // dither 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.054, 0.061, 0.071], u_colorB: [0.15, 0.25, 0.46], u_colorC: [0.62, 0.68, 0.78], }} 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_signal; 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; // Graphite base with a slow blue 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_signal * 0.55, halo * 0.45); // 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_signal, clamp(glow * 0.4, 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 < 3; 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) * 1.4; 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.25, 0.75, f)); col = mix(col, u_colorC, 0.6 * smoothstep(0.75, 1.05, length(q))); col += 0.012 * (hash(gl_FragCoord.xy) - 0.5); // dither 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.036, 0.04, 0.044], u_signal: [0.125, 0.425, 0.905], u_mist: [0.814, 0.879, 0.948], }} 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: `agent-orb` --- # 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-xl bg-kura-surface-raised px-3.5 py-3 text-sm leading-6 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-xl bg-kura-surface-raised px-3.5 py-3 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 > Quiet ring spinner (faint track, turning quarter arc) for indeterminate loading; 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: The arc stops rotating and the whole ring gently pulses in opacity instead. ## 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` --- # Status Glyph > Internal status glyph shared by agent surfaces: queued, running, waiting on you, done, failed, skipped and paused, drawn crisply in SVG. - **Slug:** `status-glyph` · **Category:** primitives · **Status:** beta - **Import:** `import { AgentStatus, StatusGlyph } from "@kura-ui/react/status-glyph";` - **Docs:** https://kuro.abstergo.fyi/components/status-glyph - **Registry item:** https://kuro.abstergo.fyi/r/status-glyph.json - **Tags:** status, agent, glyph, internal ## Install ```bash # shadcn registry (copies source into your project) npx shadcn@latest add https://kuro.abstergo.fyi/r/status-glyph.json # Kura CLI (same, plus dependency resolution and --json output) npx @kura-ui/cli add status-glyph # npm package npm install @kura-ui/react ``` ## When to use - Inside an agent surface (task list, fleet, trace, run header) to show the state of a run, step or subagent the same way everywhere. ## When not to use - A whole tool invocation with arguments and a timer — use tool-call. - A general loading indicator with no agent state — use thinking-indicator. ## Props | Prop | Type | Default | Required | Description | | --- | --- | --- | --- | --- | | `status` | `"queued" \| "running" \| "waiting" \| "done" \| "failed" \| "skipped" \| "paused"` | — | yes | The state to draw. running = turning arc in the signal colour; waiting = amber ring with a pulsing dot (the agent needs you). | | `size` | `"sm" \| "md" \| "lg"` | `"md"` | no | 14, 16 or 20px. | | `label` | `string \| null` | — | no | Spoken text (role="img"). Default the state name, e.g. "Running". Pass null when adjacent text already states it. | Native attributes of the root element, `className` and `ref` are passed through. ## Anatomy - **StatusGlyph** (`data-slot="status-glyph"`) — Root span with `data-status`; contains one 16-unit SVG. ## Accessibility - Has role="img" with the state as its name, unless label={null}, in which case it is aria-hidden. - State is never conveyed by colour alone: each state has a distinct shape. - Reduced motion: The running arc stops turning and the waiting dot stops pulsing. ## Notes for agents - Use this rather than inventing per-component status dots, so all agent surfaces share one vocabulary. ## Examples ### Running (minimal) ```tsx import { StatusGlyph } from "@kura-ui/react/status-glyph"; export function StatusGlyphMinimal() { return <StatusGlyph status="running" />; } ``` ### Every state and size (full) ```tsx import { type AgentStatus, StatusGlyph } from "@kura-ui/react/status-glyph"; const STATES: AgentStatus[] = [ "queued", "running", "waiting", "done", "failed", "skipped", "paused", ]; export function StatusGlyphFull() { return ( <div className="grid grid-cols-[auto_repeat(3,auto)] items-center gap-x-6 gap-y-3 text-[13px]"> {STATES.map((s) => ( <div key={s} className="contents"> <span className="text-kura-fg-muted capitalize">{s}</span> <StatusGlyph status={s} size="sm" /> <StatusGlyph status={s} /> <StatusGlyph status={s} size="lg" /> </div> ))} </div> ); } ``` ## Dependencies - npm: none - Kura registry items: `kura-theme`, `utils` - Related: `task-list`, `agent-fleet`, `trace-waterfall`, `run-header`, `tool-call` --- # 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 [complete, setComplete] = React.useState(false); // biome-ignore lint/correctness/useExhaustiveDependencies: `run` restarts the fake stream React.useEffect(() => { const controller = new AbortController(); setText(""); setStreaming(true); setComplete(false); (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={() => setComplete(true)} className="min-h-32" /> <div className="flex h-6 items-center justify-between"> <span className="text-kura-fg-subtle text-xs tabular-nums"> {complete ? `Done · ${text.length} characters` : "Receiving tokens…"} </span> {complete && ( <Button variant="ghost" size="xs" className="animate-kura-fade-in" 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` --- # Task List > The agent's plan as a todo list: segmented progress, shimmering current task, live and final durations, failure details, sub-tasks and a folded Completed group. - **Slug:** `task-list` · **Category:** agent · **Status:** beta - **Import:** `import { TaskList, TaskListItem } from "@kura-ui/react/task-list";` - **Docs:** https://kuro.abstergo.fyi/components/task-list - **Registry item:** https://kuro.abstergo.fyi/r/task-list.json - **Tags:** agent, plan, todo, tasks, checklist, progress, claude-code, run ## Install ```bash # shadcn registry (copies source into your project) npx shadcn@latest add https://kuro.abstergo.fyi/r/task-list.json # Kura CLI (same, plus dependency resolution and --json output) npx @kura-ui/cli add task-list # npm package npm install @kura-ui/react ``` ## When to use - Show the todo list a coding agent maintains while it works (Claude Code TodoWrite, Codex plan, Cursor tasks) in a run sidebar or panel. - Give a dense, scannable answer to 'what is the agent doing and what is left?' — '3 of 7' plus one row per task. - Let the user click a task to show its output or diff next to the list (`onSelect` + `selectedId`). - Show a failed task with its reason (`detail`) and a task blocked on the human (`waiting`). ## When not to use - A narrative step timeline with connectors and inline tool calls under each step — use agent-timeline. - Parallel subagents working at the same time — use agent-fleet. - Timing analysis of nested spans on a shared time axis — use trace-waterfall. - A single tool invocation with arguments and result — use tool-call. ## Props | Prop | Type | Default | Required | Description | | --- | --- | --- | --- | --- | | `items` | `readonly TaskListItem[]` | — | yes | The plan, in order. TaskListItem = { id, title, status: "queued" \| "running" \| "waiting" \| "done" \| "failed" \| "skipped" \| "paused", detail?, durationMs?, startedAt?, children? }. | | `title` | `React.ReactNode` | `"Plan"` | no | Heading in the panel header (panel variant only). | | `actions` | `React.ReactNode` | — | no | Controls on the right of the header, after the progress bar (e.g. an IconButton). | | `variant` | `"panel" \| "plain"` | `"panel"` | no | panel = card with header, '3 of 7' and segmented progress; plain = rows only, for embedding in your own sidebar. | | `collapseCompleted` | `boolean` | `true` | no | Fold the leading run of finished (done/skipped) items into a 'Completed (n)' row while work remains. Needs at least three finished items; a fully finished plan is shown in full. | | `completedOpen` | `boolean` | — | no | Whether the Completed group is expanded (controlled). | | `defaultCompletedOpen` | `boolean` | `false` | no | Initial expanded state of the Completed group when uncontrolled. | | `onCompletedOpenChange` | `(open: boolean) => void` | — | no | Called when the Completed group is toggled. | | `selectedId` | `string \| null` | — | no | Highlighted item (bg-kura-active plus a 2px accent bar). Purely visual; pair with onSelect. | | `onSelect` | `(id: string, item: TaskListItem) => void` | — | no | Makes rows buttons (with Up/Down/Home/End navigation) and reports the clicked item. Without it rows are static. | | `empty` | `React.ReactNode` | — | no | Content when `items` is empty. Default: a quiet 'No plan yet' state. | | `label` | `string` | — | no | Accessible name of the list. Default: `title` when it is a string, else 'Plan'. | Native attributes of the root element, `className` and `ref` are passed through. ## Anatomy - **TaskList** (`data-slot="task-list"`) — Root. `data-variant`, `data-progress="done/total"`; contains a polite status region. - **Header** (`data-slot="task-list-header"`) — h-10 header: title, mono 'n of m', segmented progress, actions. - **Progress** (`data-slot="task-list-progress"`) — One 4px segment per top-level item, coloured by status (neutral done, blue running, amber waiting, red failed). - **Completed** (`data-slot="task-list-completed"`) — The folded group of finished items. `data-state="open" | "closed"`; its button has aria-expanded. - **Item** (`data-slot="task-list-item"`) — <li> with `data-status` and `data-selected`; the running item has aria-current="step". - **Row** (`data-slot="task-list-row"`) — The row: StatusGlyph, title, detail, duration. A <button> when onSelect is set. - **Title** (`data-slot="task-list-title"`) — Shimmers while running; muted when done; struck through when skipped. Status is spoken after it. - **Detail** (`data-slot="task-list-detail"`) — Second line. Red for failed, amber for waiting, subtle otherwise. - **Duration** (`data-slot="task-list-duration"`) — Mono, tabular, width-reserved. Live clock (0:42) while running, final duration (1m 12s) after. - **Children** (`data-slot="task-list-children"`) — Nested <ul> of sub-tasks with a hairline guide; the parent shows 'done/total'. - **Empty** (`data-slot="task-list-empty"`) — Rendered when there are no items. ## Accessibility - Role: `list` - A <ul> labelled by `label`/`title`; each item speaks its status after the title (“Run pnpm test (failed)”), and the running item has aria-current="step". - A polite status region announces the current task (“Task 4 of 7: Patch src/middleware.ts”), a failure, “Waiting for you” or “All tasks complete”. Live timers are never announced. - With onSelect, rows are buttons with aria-pressed reflecting selectedId; the Completed toggle has aria-expanded/aria-controls. - Status is never colour-only: the glyph shape and the spoken status carry it. - Reduced motion: Rows fade in without rising, the title shimmer and running segment pulse stop, and the chevron turns without animating. | Keys | Action | | --- | --- | | Tab | Moves into the list (rows are buttons when onSelect is set). | | ArrowDown / ArrowUp | Moves focus to the next / previous row. | | Home / End | Moves focus to the first / last row. | | Enter / Space | Selects the focused task, or toggles the Completed group. | ## Notes for agents - Map a model-maintained todo list directly: pending → queued, in_progress → running, completed → done. Keep ids stable so rows don't remount. - Pass `startedAt` for the running item (from your server) so the live timer survives reloads; pass `durationMs` once it finishes. - Only one top-level item should be `running`; it carries the blue signal and the shimmer. - Use `waiting` (amber) only when the agent is blocked on the human, and put the ask in `detail`. - The Completed fold only collapses the *leading* finished items, so a failed task in the middle is never hidden. ## Examples ### A plan in progress (minimal) Two done, one running with a live timer, one queued. ```tsx import { TaskList } from "@kura-ui/react/task-list"; export function TaskListMinimal() { return ( <TaskList className="w-full max-w-md" items={[ { id: "read", title: "Read routes in src/app", status: "done", durationMs: 21_400 }, { id: "map", title: "Map call sites of fetchUser()", status: "done", durationMs: 48_200 }, { id: "patch", title: "Patch src/auth/client.ts", status: "running", startedAt: Date.now() - 34_000, }, { id: "test", title: "Run pnpm test", status: "queued" }, ]} /> ); } ``` ### Live run (full) The auth-client migration plays out: finished tasks fold into Completed, sub-tasks tick, the test run fails, a fix task appears, the re-run passes, the reviewer signs off and the PR opens. ```tsx "use client"; import { RotateCcw } from "lucide-react"; import * as React from "react"; import { IconButton } from "@kura-ui/react/icon-button"; import { TaskList, type TaskListItem } from "@kura-ui/react/task-list"; const PLAN: TaskListItem[] = [ { id: "routes", title: "Read routes in src/app", status: "done", durationMs: 21_400 }, { id: "map", title: "Map call sites of fetchUser()", status: "done", durationMs: 48_200, detail: "14 call sites across 9 files", }, { id: "client", title: "Patch src/auth/client.ts", status: "done", durationMs: 72_900, }, { id: "middleware", title: "Patch src/middleware.ts", status: "running" }, { id: "tests", title: "Update tests", status: "queued", children: [ { id: "tests-login", title: "login.test.ts", status: "queued" }, { id: "tests-session", title: "session.test.ts", status: "queued" }, ], }, { id: "run", title: "Run pnpm test", status: "queued" }, { id: "review", title: "Review the diff", status: "queued" }, { id: "pr", title: "Open pull request", status: "queued" }, ]; function set(items: TaskListItem[], id: string, patch: Partial<TaskListItem>): TaskListItem[] { return items.map((item) => item.id === id ? { ...item, ...patch } : item.children ? { ...item, children: set([...item.children], id, patch) } : item, ); } const SCRIPT: Beat[] = [ { at: 2600, patch: (s) => set( set(set(s, "middleware", { status: "done", durationMs: 41_300 }), "tests", { status: "running", startedAt: Date.now(), }), "tests-login", { status: "running", startedAt: Date.now() }, ), }, { at: 4400, patch: (s) => set(set(s, "tests-login", { status: "done", durationMs: 18_200 }), "tests-session", { status: "running", startedAt: Date.now(), }), }, { at: 6000, patch: (s) => set( set(set(s, "tests-session", { status: "done", durationMs: 12_700 }), "tests", { status: "done", durationMs: 30_900, }), "run", { status: "running", startedAt: Date.now(), detail: "pnpm test --filter @acme/web" }, ), }, { at: 8400, patch: (s) => insertAfter( set(s, "run", { status: "failed", durationMs: 38_400, detail: "login.test.ts › refreshes an expired session — expected 200, received 401", }), "run", { id: "fix", title: "Retry refresh with the rotated token", status: "running", startedAt: Date.now(), detail: "src/auth/client.ts:88", }, ), }, { at: 11_000, patch: (s) => set(set(s, "fix", { status: "done", durationMs: 52_100, detail: undefined }), "run", { status: "running", startedAt: Date.now(), detail: "pnpm test --filter @acme/web", }), }, { at: 13_200, patch: (s) => set(set(s, "run", { status: "done", durationMs: 36_800, detail: "142 passed" }), "review", { status: "running", startedAt: Date.now(), detail: "reviewer subagent", }), }, { at: 15_400, patch: (s) => set( set(s, "review", { status: "done", durationMs: 186_000, detail: "2 nits, 0 blocking" }), "pr", { status: "running", startedAt: Date.now() }, ), }, { at: 17_000, patch: (s) => set(s, "pr", { status: "done", durationMs: 48_100, detail: "acme/web#482" }), }, ]; function insertAfter(items: TaskListItem[], id: string, next: TaskListItem): TaskListItem[] { const i = items.findIndex((item) => item.id === id); return [...items.slice(0, i + 1), next, ...items.slice(i + 1)]; } export function TaskListFull() { const [items, setItems] = React.useState<TaskListItem[]>(() => set(PLAN, "middleware", { startedAt: Date.now() - 27_000 }), ); const [selectedId, setSelectedId] = React.useState<string | null>(null); const [run, setRun] = React.useState(0); // biome-ignore lint/correctness/useExhaustiveDependencies: `run` replays the script React.useEffect(() => { setItems(set(PLAN, "middleware", { startedAt: Date.now() - 27_000 })); const timers = SCRIPT.map((beat) => setTimeout(() => setItems(beat.patch), beat.at)); return () => timers.forEach(clearTimeout); }, [run]); return ( <TaskList className="w-full max-w-md" items={items} label="Migrate to @acme/auth client" selectedId={selectedId} onSelect={(id) => setSelectedId((cur) => (cur === id ? null : id))} actions={ <IconButton label="Replay" icon={<RotateCcw />} variant="ghost" size="xs" className="-mr-1.5" onClick={() => setRun((r) => r + 1)} /> } /> ); } ``` ### Every state (state) Done, skipped, waiting for approval, failed with a reason, paused and queued. ```tsx import { TaskList } from "@kura-ui/react/task-list"; export function TaskListStates() { return ( <TaskList className="w-full max-w-md" title="Release checklist" collapseCompleted={false} items={[ { id: "a", title: "Bump version to 2.4.0", status: "done", durationMs: 3_200 }, { id: "b", title: "Regenerate API types", status: "skipped", detail: "Schema unchanged since 2.3.1", }, { id: "c", title: "Run database migration 0042_sessions", status: "waiting", detail: "Needs your approval — touches production", }, { id: "d", title: "Build preview deployment", status: "failed", durationMs: 84_100, detail: "next build exited with code 1 — Type error in src/middleware.ts:31", }, { id: "e", title: "Notify #releases", status: "paused" }, { id: "f", title: "Tag release", status: "queued" }, ]} /> ); } ``` ### Plan beside output (composition) The plain variant in a sidebar; selecting a task shows its output on the right. ```tsx "use client"; import * as React from "react"; import { TaskList, type TaskListItem } from "@kura-ui/react/task-list"; const OUTPUT: Record<string, string[]> = { routes: [ "$ rg --files src/app | rg route", "src/app/api/session/route.ts", "src/app/login/page.tsx", "src/app/(app)/layout.tsx", ], map: [ "explorer · 14 call sites of fetchUser()", "src/app/(app)/layout.tsx:12", "src/components/nav/user-menu.tsx:8", "src/lib/server/session.ts:44", "… 11 more", ], client: [ "Edited src/auth/client.ts +64 −22", "Replaced legacy REST session calls", "with createAuthClient({ baseUrl })", ], run: [ "$ pnpm test", "✕ login.test.ts › refreshes an expired session", " expected 200, received 401", "141 passed, 1 failed (38.4s)", ], }; export function TaskListComposition() { const [selectedId, setSelectedId] = React.useState("run"); const [t0] = React.useState(() => Date.now()); const items: TaskListItem[] = [ { id: "routes", title: "Read routes", status: "done", durationMs: 21_400 }, { id: "map", title: "Map fetchUser() calls", status: "done", durationMs: 48_200 }, { id: "client", title: "Patch auth client", status: "done", durationMs: 72_900 }, { id: "run", title: "Run pnpm test", status: "failed", durationMs: 38_400, detail: "1 failed", }, { id: "fix", title: "Fix token refresh", status: "running", startedAt: t0 - 19_000 }, ]; const lines = OUTPUT[selectedId] ?? ["No output yet."]; return ( <div className="grid w-full max-w-2xl overflow-hidden rounded-kura-xl bg-kura-surface shadow-kura-sm sm:grid-cols-[240px_1fr]"> <div className="border-kura-border-subtle border-b sm:border-r sm:border-b-0"> <div className="flex h-10 items-center px-3.5 font-medium text-[13px]">Plan</div> <TaskList variant="plain" collapseCompleted={false} items={items} selectedId={selectedId} onSelect={(id) => setSelectedId(id)} label="Plan" /> </div> <div className="flex min-w-0 flex-col"> <div className="flex h-10 items-center gap-2 border-kura-border-subtle border-b px-3.5"> <span className="truncate font-medium text-[13px]"> {items.find((i) => i.id === selectedId)?.title} </span> <span className="ml-auto font-kura-mono text-[12px] text-kura-fg-subtle">output</span> </div> <pre className="m-0 min-h-40 flex-1 overflow-auto bg-kura-surface-sunken px-3.5 py-3 font-kura-mono text-[12px] text-kura-fg-muted leading-5"> {lines.join("\n")} </pre> </div> </div> ); } ``` ## Dependencies - npm: `lucide-react` - Kura registry items: `kura-theme`, `kura-format`, `shimmer-text`, `status-glyph`, `use-controllable-state`, `use-elapsed`, `utils` - Related: `agent-timeline`, `agent-fleet`, `run-header`, `trace-waterfall`, `status-glyph` --- # Terminal > Streamed command output that behaves like a real terminal: ANSI colours, progress-bar rewrites, stick-to-bottom, live clock and exit-code badge. - **Slug:** `terminal` · **Category:** workspace · **Status:** experimental - **Import:** `import { AnsiColor, AnsiScreen, AnsiSpan, AnsiStyle, Terminal, TerminalStatus } from "@kura-ui/react/terminal";` - **Docs:** https://kuro.abstergo.fyi/components/terminal - **Registry item:** https://kuro.abstergo.fyi/r/terminal.json - **Tags:** terminal, shell, logs, ansi, streaming, command, agent, workspace ## Install ```bash # shadcn registry (copies source into your project) npx shadcn@latest add https://kuro.abstergo.fyi/r/terminal.json # Kura CLI (same, plus dependency resolution and --json output) npx @kura-ui/cli add terminal # npm package npm install @kura-ui/react ``` ## When to use - Show a shell command an agent ran (pnpm test, git status, a build) with its output, while it runs and after. - Stream a child process's stdout (AsyncIterable<string>) or a growing log string into the UI. - Long logs where the tail matters: collapse to the last N lines with “Show all N lines”. - A dev-server or watcher log with a Stop control in the header. ## When not to use - Source code or a snippet to copy — use code-block. - Reviewing file edits — use diff-view. - A tool call whose output is structured JSON — use tool-call. - Interactive shells that take keyboard input — this renders output only (no PTY, no input line). ## Props | Prop | Type | Default | Required | Description | | --- | --- | --- | --- | --- | | `command` | `string` | — | no | The command, shown on the prompt line (`$ pnpm test`) and in the accessible name. | | `lines` | `readonly string[] \| string` | — | no | Output as lines or one growing string. ANSI SGR (colours 30–37/90–97, 256/truecolour approximated, bold, dim, italic, underline, inverse) and cursor controls (\r, erase line, cursor up, backspace) are rendered; OSC titles/links are stripped. Append-only updates are parsed incrementally. | | `stream` | `AsyncIterable<string>` | — | no | Output as a stream of chunks; takes precedence over `lines`. Chunks may split lines and escape sequences. Status is “running” until it ends. | | `onStreamEnd` | `() => void` | — | no | Called once `stream` has ended. | | `status` | `"idle" \| "running" \| "done" \| "failed"` | — | no | Lifecycle. Default: from exitCode (0 → done, otherwise failed), "running" while a stream is open, else "idle" (no glyph). | | `exitCode` | `number \| null` | — | no | Exit code, shown as a badge once finished (red when non-zero). | | `startedAt` | `Date \| number` | — | no | Start time for the live clock. Default: when status became running. | | `duration` | `number` | — | no | Final duration in ms for persisted runs. Default: measured from running → finished in this session. | | `cwd` | `string` | — | no | Working directory in the header, e.g. "~/acme/web". | | `title` | `React.ReactNode` | — | no | Header title, e.g. "Run tests". Default: the cwd, or "Terminal". | | `prompt` | `string` | `"$"` | no | Prompt glyph before the command. | | `maxHeight` | `number` | `320` | no | Viewport height in px. Output sticks to the bottom while the user is there; scrolling up shows “Jump to latest” / “N new lines”. | | `maxLines` | `number` | — | no | Collapse to the last N lines with a “Show all N lines” control at the top. | | `expanded` | `boolean` | — | no | Showing every line past maxLines (controlled). | | `defaultExpanded` | `boolean` | `false` | no | Initial expanded state when uncontrolled. | | `onExpandedChange` | `(expanded: boolean) => void` | — | no | Called when “Show all” / “Show last N” is used. | | `wrap` | `boolean` | `true` | no | Soft-wrap long lines. | | `copyable` | `boolean` | `true` | no | Show the copy button: copies `$ command` plus the plain output (no escape codes). | | `onCopy` | `(text: string) => void` | — | no | Called with the copied text after a successful copy. | | `header` | `boolean` | `true` | no | Show the header row. | | `actions` | `React.ReactNode` | — | no | Extra header controls before the copy button, e.g. a Stop Button. | Native attributes of the root element, `className` and `ref` are passed through. ## Anatomy - **Terminal** (`data-slot="terminal"`) — `data-status="idle" | "running" | "done" | "failed"`, `data-state="collapsed" | "expanded"` when maxLines applies. - **Header** (`data-slot="terminal-header"`) — Status glyph, title (`terminal-title`), cwd, live clock / duration (`terminal-elapsed`), exit badge (`terminal-exit-code`), actions, copy. - **Output** (`data-slot="terminal-output"`) — `role="log"` scroll viewport (aria-live off), keyboard-scrollable; prompt line (`terminal-command`) and lines (`terminal-line`). - **Cursor** (`data-slot="terminal-cursor"`) — Block cursor at the live edge while running. - **Expand** (`data-slot="terminal-expand"`) — “Show all N lines” row when collapsed (`terminal-collapse` to collapse again). - **Jump** (`data-slot="terminal-jump"`) — Floating “Jump to latest” / “N new lines” pill when scrolled away from the bottom. ## Accessibility - Role: `log` - The output is a role=log region named “Output of <command>” with aria-live off, so streaming never floods a screen reader. - A separate polite status announces only transitions: “pnpm test running”, “pnpm test failed, exit code 1”, and copy confirmation. - The viewport is focusable (Tab) and scrolls with arrow keys / Page Up / Page Down. - Status is text as well as colour: the exit badge reads “exit 1”; the glyph is decorative next to it. - Reduced motion: The cursor stops pulsing, the running glyph stops spinning, and the copy icon swap and pill entrance become plain fades. Jump to latest still scrolls smoothly only if the browser allows it. | Keys | Action | | --- | --- | | Tab | Focus the output, then the expand, jump, action and copy buttons | | Arrow keys / Page Up / Page Down | Scroll the focused output | | Enter / Space | Activate Show all / Jump to latest / Copy | ## Notes for agents - Pass raw process output; don't strip ANSI codes. Escape sequences split across chunks are buffered. - For a growing string, only append — replacing earlier text triggers a full re-parse (still correct, just slower). - Keep the same Terminal mounted from running → done so the measured duration works; for history pass `duration`. - `stream` is consumed once; create a new iterable to restart. Set `exitCode` in onStreamEnd to finish with a badge. - Colours map to Kura tokens; override any of them with --kura-terminal-{red,green,yellow,blue,magenta,cyan,white,gray,black} on a parent. - Helpers exported alongside: parseAnsi(text), stripAnsi(text), AnsiScreen (incremental). ## Examples ### Finished command (minimal) `git status --short` with coloured output and an exit badge. ```tsx import { Terminal } from "@kura-ui/react/terminal"; const red = (s: string) => `\x1b[31m${s}\x1b[39m`; export function TerminalMinimal() { return ( <Terminal className="w-full max-w-2xl" cwd="~/acme/web" command="git status --short" exitCode={0} lines={[ ` ${red("M")} src/auth/client.ts`, ` ${red("M")} src/middleware.ts`, ` ${red("M")} src/auth/__tests__/login.test.ts`, ` ${red("D")} src/lib/legacy-session.ts`, ]} /> ); } ``` ### Streaming test run (full) `pnpm test` streams vitest output line by line (live clock, cursor, stick-to-bottom), ends with one failing test and exit 1. ```tsx "use client"; import * as React from "react"; import { Terminal } from "@kura-ui/react/terminal"; const TEST_OUTPUT = [ "", `> @acme/web@0.42.0 test ${dim("/Users/kura/acme/web")}`, "> vitest run", "", ` ${badge("RUN", 36)} ${cyan("v3.2.4")} ${gray("/Users/kura/acme/web")}`, "", ` ${green("✓")} ${dim("src/auth/__tests__/")}session.test.ts ${gray("(6 tests)")} ${gray("41ms")}`, ` ${green("✓")} ${dim("src/")}middleware.test.ts ${gray("(4 tests)")} ${gray("18ms")}`, ` ${green("✓")} ${dim("src/routes/__tests__/")}account.test.ts ${gray("(9 tests)")} ${gray("112ms")}`, ` ${yellow("❯")} ${dim("src/auth/__tests__/")}login.test.ts ${gray("(5 tests | ")}${red("1 failed")}${gray(")")} ${gray("87ms")}`, ` ${green("✓")} login ${gray(">")} detects an expired session ${gray("2ms")}`, ` ${red("×")} login ${gray(">")} refreshes an expired session ${gray("14ms")}`, ` ${red("→ expected 'tok_expired' to be 'tok_next' // Object.is equality")}`, ` ${green("✓")} ${dim("src/lib/__tests__/")}http.test.ts ${gray("(7 tests)")} ${gray("9ms")}`, "", red(`⎯⎯⎯⎯⎯⎯⎯ ${bold("Failed Tests 1")} ⎯⎯⎯⎯⎯⎯⎯`), "", ` ${badge("FAIL", 31)} src/auth/__tests__/login.test.ts ${gray(">")} login ${gray(">")} refreshes an expired session`, `${red(bold("AssertionError"))}${red(": expected 'tok_expired' to be 'tok_next' // Object.is equality")}`, "", `${green("- Expected")}`, `${red("+ Received")}`, "", `${green("- tok_next")}`, `${red("+ tok_expired")}`, "", ` ${cyan("❯")} src/auth/__tests__/login.test.ts:18:32`, gray(" 16| const next = await refreshSession(session);"), gray(' 17| expect(next.user.id).toBe("u_1");'), ` 18| expect(next.refreshToken).toBe(${green('"tok_next"')});`, ` | ${red(" ^")}`, "", ` ${dim("Test Files")} ${bold(red("1 failed"))} ${gray("|")} ${bold(green("4 passed"))} ${gray("(5)")}`, ` ${dim("Tests")} ${bold(red("1 failed"))} ${gray("|")} ${bold(green("30 passed"))} ${gray("(31)")}`, ` ${dim("Start at")} 14:02:11`, ` ${dim("Duration")} 1.42s ${gray("(transform 212ms, setup 0ms, collect 610ms, tests 267ms)")}`, "", `${red(" ELIFECYCLE ")} ${red("Test failed. See above for more details.")}`, ]; async function* replay(lines: string[], signal: { cancelled: boolean }) { for (const [i, line] of lines.entries()) { // Collection is slow, results arrive in bursts, the summary lands at once. const wait = i < 4 ? 260 : i < 14 ? 180 + (i % 3) * 140 : 35; await new Promise((r) => setTimeout(r, wait)); if (signal.cancelled) return; yield `${line}\n`; } } const dim = (s: string) => `\x1b[2m${s}\x1b[22m`; const bold = (s: string) => `\x1b[1m${s}\x1b[22m`; const red = (s: string) => `\x1b[31m${s}\x1b[39m`; const green = (s: string) => `\x1b[32m${s}\x1b[39m`; const yellow = (s: string) => `\x1b[33m${s}\x1b[39m`; const cyan = (s: string) => `\x1b[36m${s}\x1b[39m`; const gray = (s: string) => `\x1b[90m${s}\x1b[39m`; const badge = (s: string, color: 31 | 32 | 34 | 36) => `\x1b[1;7;${color}m ${s} \x1b[0m`; export function TerminalFull() { const [stream, setStream] = React.useState<AsyncIterable<string>>(); const [exitCode, setExitCode] = React.useState<number | null>(null); React.useEffect(() => { const signal = { cancelled: false }; setStream(replay(TEST_OUTPUT, signal)); return () => { signal.cancelled = true; }; }, []); return ( <Terminal className="w-full max-w-2xl" title="Run tests" cwd="~/acme/web" command="pnpm test" stream={stream} status={exitCode == null ? "running" : undefined} exitCode={exitCode} onStreamEnd={() => setExitCode(1)} maxHeight={360} /> ); } ``` ### Collapsed build log (state) A Next.js build collapsed to the last 9 lines; one line is a \r-rewritten progress counter. ```tsx import { Terminal } from "@kura-ui/react/terminal"; const BUILD_OUTPUT = [ ` ${bold("▲ Next.js 16.0.1")}`, ` - Environments: .env.production`, "", ` Creating an optimized production build ...`, ` ${green("✓")} Compiled successfully in 8.4s`, ` ${green("✓")} Linting and checking validity of types`, ` ${green("✓")} Collecting page data`, // A progress line rewritten in place with carriage returns. ` Generating static pages (0/14)\r Generating static pages (7/14)\r ${green("✓")} Generating static pages (14/14)`, ` ${green("✓")} Finalizing page optimization`, "", `${bold("Route (app)")} ${bold("Size")} ${bold("First Load JS")}`, `┌ ○ / 5.21 kB ${green("112 kB")}`, `├ ○ /_not-found 990 B ${green("103 kB")}`, `├ ƒ /account 3.84 kB ${green("118 kB")}`, `├ ƒ /api/health 142 B ${green("102 kB")}`, `├ ○ /login 2.67 kB ${green("115 kB")}`, `└ ○ /signup 2.71 kB ${green("115 kB")}`, `+ First Load JS shared by all ${green("102 kB")}`, "", `ƒ Middleware ${green("34.1 kB")}`, "", `○ (Static) prerendered as static content`, `ƒ (Dynamic) server-rendered on demand`, ]; const bold = (s: string) => `\x1b[1m${s}\x1b[22m`; const green = (s: string) => `\x1b[32m${s}\x1b[39m`; export function TerminalCollapsed() { return ( <Terminal className="w-full max-w-2xl" title="Build" cwd="~/acme/web" command="pnpm build" lines={BUILD_OUTPUT} exitCode={0} duration={23_400} maxLines={9} wrap={false} /> ); } ``` ### Dev server with Stop (composition) A Button in `actions` stops a dev server that keeps logging. ```tsx "use client"; import { Square } from "lucide-react"; import * as React from "react"; import { Button } from "@kura-ui/react/button"; import { Terminal } from "@kura-ui/react/terminal"; const green = (s: string) => `\x1b[32m${s}\x1b[39m`; const DEV_LINES = [ ` ${bold("▲ Next.js 16.0.1")} (Turbopack)`, ` - Local: ${cyan("http://localhost:3000")}`, ` - Network: ${cyan("http://192.168.1.24:3000")}`, "", ` ${green("✓")} Starting...`, ` ${green("✓")} Ready in 1.1s`, ` ${gray("○")} Compiling /login ...`, ` ${green("✓")} Compiled /login in 640ms`, ` GET /login ${green("200")} in 702ms`, ` POST /api/auth/session ${green("200")} in 48ms`, ` GET /account ${green("200")} in 131ms`, ` GET /api/auth/session ${yellow("401")} in 12ms`, ` GET /login?next=%2Faccount ${green("200")} in 22ms`, ]; const bold = (s: string) => `\x1b[1m${s}\x1b[22m`; const yellow = (s: string) => `\x1b[33m${s}\x1b[39m`; const cyan = (s: string) => `\x1b[36m${s}\x1b[39m`; const gray = (s: string) => `\x1b[90m${s}\x1b[39m`; export function TerminalComposition() { const [lines, setLines] = React.useState<string[]>(DEV_LINES.slice(0, 6)); const [stopped, setStopped] = React.useState(false); React.useEffect(() => { if (stopped) return; const id = setInterval(() => { setLines((prev) => prev.length < DEV_LINES.length ? [...prev, DEV_LINES[prev.length]!] : [...prev, ` GET /api/health ${green("200")} in ${4 + (prev.length % 7)}ms`], ); }, 1400); return () => clearInterval(id); }, [stopped]); return ( <Terminal className="w-full max-w-2xl" title="Dev server" cwd="~/acme/web" command="pnpm dev" lines={stopped ? [...lines, "^C"] : lines} status={stopped ? "done" : "running"} maxHeight={240} actions={ !stopped && ( <Button size="xs" variant="ghost" onClick={() => setStopped(true)}> <Square aria-hidden className="size-3 fill-current" /> Stop </Button> ) } /> ); } ``` ## Dependencies - npm: `lucide-react` - Kura registry items: `kura-theme`, `icon-button`, `kura-format`, `status-glyph`, `use-controllable-state`, `use-elapsed`, `utils` - Related: `diff-view`, `file-changes`, `code-block`, `tool-call`, `agent-timeline` --- # 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 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 blue default when it means “the model is working”; use a neutral grey for secondary, low-priority activity. - 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-surface-sunken text-kura-fg-muted shadow-kura-xs"> <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`, `agent-orb`, `streaming-text`, `message`, `run-header` --- # 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 = blue pulse + shimmering title + ticking timer; success = check; error = cross (details open by default); awaiting-approval = blue 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" /> {status === "success" && ( <Button variant="ghost" size="xs" className="animate-kura-fade-in self-end" 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`, `status-glyph`, `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` --- # Trace Waterfall > Span tree on a shared time axis for agent runs: nested agent, LLM, tool and retrieval spans, live bars, a details row and keyboard tree navigation. - **Slug:** `trace-waterfall` · **Category:** agent · **Status:** beta - **Import:** `import { TraceSpan, TraceSpanKind, TraceWaterfall } from "@kura-ui/react/trace-waterfall";` - **Docs:** https://kuro.abstergo.fyi/components/trace-waterfall - **Registry item:** https://kuro.abstergo.fyi/r/trace-waterfall.json - **Tags:** agent, trace, observability, spans, waterfall, timeline, tokens, latency ## Install ```bash # shadcn registry (copies source into your project) npx shadcn@latest add https://kuro.abstergo.fyi/r/trace-waterfall.json # Kura CLI (same, plus dependency resolution and --json output) npx @kura-ui/cli add trace-waterfall # npm package npm install @kura-ui/react ``` ## When to use - Show where the time (and tokens, and money) went in an agent run: which model calls, tool calls and subagents ran, nested, and when. - Debug a slow or failed run: spot the long LLM call, the failed `pnpm test`, the subagent that ran in parallel. - Watch a run live: running spans grow against the axis and a 'now' line moves (pass `startedAt` or drive `now`). - Inspect one span's input, output, error, model, tokens and cost inline by selecting it. ## When not to use - The agent's plan or todo list (what it intends to do) — use task-list. - A narrative of steps with tool calls attached — use agent-timeline. - Parallel subagents as a live roster with activity and progress — use agent-fleet. - A single tool invocation — use tool-call. ## Props | Prop | Type | Default | Required | Description | | --- | --- | --- | --- | --- | | `spans` | `readonly TraceSpan[]` | — | yes | Root spans (usually one agent span). TraceSpan = { id, name, kind: "agent" \| "llm" \| "tool" \| "retrieval", start (ms since run start), end? (omit while running), status: AgentStatus, meta? (mono hint: path, command), model?, tokens? { input, output }, cost? (USD), input?, output?, error?, children? }. | | `title` | `React.ReactNode` | `"Trace"` | no | Header title. | | `actions` | `React.ReactNode` | — | no | Controls on the right of the header (e.g. a replay or open-in-LangSmith button). | | `now` | `number` | — | no | Current run time in ms since start (a controlled clock). Running spans end here and the 'now' line sits here. Use it for replays and server-driven clocks. | | `startedAt` | `Date \| number` | — | no | Wall-clock start of the run. When given (and `now` isn't), running spans grow live, ticking every 250ms. Without either, running spans end at the latest known time. | | `selectedId` | `string \| null` | — | no | Selected span (controlled). Its details row opens under it. | | `defaultSelectedId` | `string \| null` | `null` | no | Initially selected span when uncontrolled. May name a span that doesn't exist yet; it opens when the span appears. | | `onSelectedIdChange` | `(id: string \| null) => void` | — | no | Called when a span is selected, or with null when the selection is cleared. | | `defaultCollapsedIds` | `readonly string[]` | — | no | Spans whose subtrees start collapsed (e.g. noisy subagents). | | `renderDetails` | `(span: TraceSpan) => React.ReactNode` | — | no | Replace the details row body for a span (e.g. a CodeBlock with the diff a tool wrote). Return null to use the default stats + input/output. | | `empty` | `React.ReactNode` | — | no | Rendered when there are no spans. Default: 'No spans yet'. | | `label` | `string` | `"Trace"` | no | Accessible name of the tree. | Native attributes of the root element, `className` and `ref` are passed through. ## Anatomy - **TraceWaterfall** (`data-slot="trace-waterfall"`) — Root panel, a container-query context. `data-state="running" | "idle"`; contains a polite status region. - **Header** (`data-slot="trace-waterfall-header"`) — h-10 header: title, summary, actions. - **Summary** (`data-slot="trace-waterfall-summary"`) — Mono: span count · total duration · tokens · cost. Count/tokens/cost hide on narrow containers. - **Axis** (`data-slot="trace-waterfall-axis"`) — Sticky row with 'Span / Duration' over the tree and nice tick labels (0, 2m, 4m…) over the bars. - **Body** (`data-slot="trace-waterfall-body"`) — Scroll container. Give the root a height (e.g. `h-[480px]`) to scroll long traces under the sticky axis. - **Span** (`data-slot="trace-waterfall-span"`) — role="treeitem" with `data-kind`, `data-status`, `data-selected`; wraps the row and, when selected, its details. - **Row** (`data-slot="trace-waterfall-row"`) — h-8 grid row: indented tree cell (chevron, kind icon, name, mono meta, glyph for running/failed/waiting, duration) and the bar cell. - **Toggle** (`data-slot="trace-waterfall-toggle"`) — Chevron that collapses a subtree (pointer only; ArrowLeft/Right on the keyboard). - **Bar** (`data-slot="trace-waterfall-bar"`) — Positioned on the shared axis. Neutral greys by kind (LLM darkest), thin for agent spans; blue while running, red failed, amber waiting, ink when selected. - **Now** (`data-slot="trace-waterfall-now"`) — Hairline at the current time while any span is running. - **Details** (`data-slot="trace-waterfall-details"`) — Sunken row under the selected span: kind, start, duration, model, tokens, cost, then input and output/error. - **Duration** (`data-slot="trace-waterfall-duration"`) — Mono, tabular, width-reserved; ticks while the span runs. - **Empty** (`data-slot="trace-waterfall-empty"`) — Rendered when there are no spans. ## Accessibility - Role: `tree` - A WAI-ARIA tree: each span is a treeitem with aria-level/posinset/setsize, aria-expanded for subtrees and aria-selected; one roving tab stop. - Each treeitem is labelled “bash pnpm test, tool, 38.4s, failed” — status is spoken, never colour-only. The selected span is described by its details row. - A polite status region announces failures and “Trace complete, 11m 52s” — ticking durations are not announced. - The axis, grid lines, bars and now-line are decorative (aria-hidden or inside labelled items). - Reduced motion: Bars and the now-line jump to their new positions instead of easing; the chevron turns instantly; rows and details only fade. | Keys | Action | | --- | --- | | ArrowDown / ArrowUp | Moves focus to the next / previous visible span. | | ArrowRight | Expands a collapsed span; on an expanded span moves to its first child. | | ArrowLeft | Collapses an expanded span; otherwise moves to the parent span. | | Home / End | First / last visible span. | | Enter / Space | Selects the focused span (opens details); again to close. | | Escape | Clears the selection. | ## Notes for agents - Times are ms relative to the run start, not timestamps: convert with `span.start = +new Date(event.ts) - runStart`. - Omit `end` (and set status running) for unfinished spans; pass `startedAt` (wall clock) or `now` so they grow. - Put tokens/cost on leaf spans only. If every root span carries totals, the header uses the roots instead of summing. - Ids must be unique across the whole tree; they drive selection, collapse state and focus. - Give the root a fixed height for long traces; the axis stays sticky while the body scrolls. ## Examples ### A finished turn (minimal) One agent span with two LLM calls and a tool call. ```tsx import { TraceWaterfall } from "@kura-ui/react/trace-waterfall"; export function TraceWaterfallMinimal() { return ( <TraceWaterfall className="w-full max-w-2xl" spans={[ { id: "run", name: "Kura", kind: "agent", meta: "claude-opus-5-5", start: 0, end: 14_200, status: "done", children: [ { id: "plan", name: "Plan the fix", kind: "llm", start: 0, end: 6_400, status: "done", tokens: { input: 12_400, output: 610 }, cost: 0.06, }, { id: "read", name: "read_file", kind: "tool", meta: "src/auth/client.ts", start: 6_500, end: 6_900, status: "done", }, { id: "edit", name: "Write the patch", kind: "llm", start: 7_000, end: 14_200, status: "done", tokens: { input: 15_100, output: 1_240 }, cost: 0.08, }, ], }, ]} /> ); } ``` ### Replay of a run (full) The 12-minute auth-client migration replayed on a controlled clock: subagents, a failing pnpm test (selected, with its error), the fix, review and PR. The axis rescales as the run grows. ```tsx "use client"; import { RotateCcw } from "lucide-react"; import * as React from "react"; import { IconButton } from "@kura-ui/react/icon-button"; import { type TraceSpan, TraceWaterfall } from "@kura-ui/react/trace-waterfall"; const RUN: TraceSpan = { id: "run", name: "Kura", kind: "agent", meta: "acme/web · kura/auth-client", start: 0, end: 11 * M + 52 * S, status: "done", children: [ { id: "plan", name: "Plan the migration", kind: "llm", model: "claude-opus-5-5", start: 0, end: 9.8 * S, status: "done", tokens: { input: 18_400, output: 1_120 }, cost: 0.11, input: "Migrate acme/web from the legacy REST session API to @acme/auth. Read the routes first.", output: "1. Read routes in src/app\n2. Map call sites of fetchUser()\n3. Patch src/auth/client.ts and src/middleware.ts\n4. Update tests, run pnpm test\n5. Open a PR", }, { id: "routes", name: "read_file", kind: "tool", meta: "src/app/api/session/route.ts", start: 9.9 * S, end: 10.3 * S, status: "done", input: '{ "path": "src/app/api/session/route.ts" }', output: "export async function GET(req: Request) {\n const user = await fetchUser(req)\n …", }, { id: "search", name: "search_code", kind: "retrieval", meta: "fetchUser(", start: 10.4 * S, end: 12.1 * S, status: "done", output: "14 matches in 9 files", }, { id: "explorer", name: "explorer", kind: "agent", meta: "subagent", start: 12.5 * S, end: 62 * S, status: "done", children: [ { id: "explorer-llm", name: "Find call sites", kind: "llm", model: "claude-haiku-4-5", start: 12.6 * S, end: 21 * S, status: "done", tokens: { input: 9_800, output: 420 }, cost: 0.01, }, { id: "explorer-grep", name: "bash", kind: "tool", meta: "rg -n 'fetchUser\\(' src", start: 21.1 * S, end: 21.9 * S, status: "done", }, { id: "explorer-sum", name: "Summarize call sites", kind: "llm", model: "claude-haiku-4-5", start: 22.2 * S, end: 61.5 * S, status: "done", tokens: { input: 41_200, output: 2_300 }, cost: 0.05, }, ], }, { id: "patch", name: "Draft the client patch", kind: "llm", model: "claude-opus-5-5", start: 63 * S, end: 1 * M + 40 * S, status: "done", tokens: { input: 52_300, output: 6_900 }, cost: 0.31, }, { id: "edit-client", name: "edit_file", kind: "tool", meta: "src/auth/client.ts", start: 1 * M + 40.2 * S, end: 1 * M + 40.9 * S, status: "done", }, { id: "edit-mw", name: "edit_file", kind: "tool", meta: "src/middleware.ts", start: 2 * M + 8 * S, end: 2 * M + 8.6 * S, status: "done", }, { id: "tests", name: "test-writer", kind: "agent", meta: "subagent", start: 2 * M + 12 * S, end: 5 * M + 28 * S, status: "done", children: [ { id: "tests-llm", name: "Write session tests", kind: "llm", model: "claude-sonnet-4-5", start: 2 * M + 12 * S, end: 4 * M + 31 * S, status: "done", tokens: { input: 88_000, output: 9_400 }, cost: 0.38, }, { id: "tests-edit", name: "edit_file", kind: "tool", meta: "src/auth/login.test.ts", start: 4 * M + 32 * S, end: 4 * M + 33 * S, status: "done", }, ], }, { id: "test-1", name: "bash", kind: "tool", meta: "pnpm test", start: 5 * M + 31 * S, end: 6 * M + 9.4 * S, status: "failed", input: "pnpm test --filter @acme/web", error: "✕ login.test.ts › refreshes an expired session\n Expected: 200\n Received: 401\n\n at src/auth/client.ts:88:11\n\nTests: 1 failed, 141 passed, 142 total", }, { id: "diagnose", name: "Diagnose the failure", kind: "llm", model: "claude-opus-5-5", start: 6 * M + 10 * S, end: 7 * M + 1 * S, status: "done", tokens: { input: 71_500, output: 4_800 }, cost: 0.29, }, { id: "test-2", name: "bash", kind: "tool", meta: "pnpm test", start: 7 * M + 4 * S, end: 7 * M + 40.8 * S, status: "done", output: "Tests: 142 passed, 142 total", }, { id: "review", name: "reviewer", kind: "agent", meta: "subagent", start: 7 * M + 42 * S, end: 10 * M + 48 * S, status: "done", children: [ { id: "review-llm", name: "Review the diff", kind: "llm", model: "claude-opus-5-5", start: 7 * M + 42 * S, end: 10 * M + 48 * S, status: "done", tokens: { input: 104_000, output: 8_100 }, cost: 0.42, }, ], }, { id: "pr", name: "bash", kind: "tool", meta: "gh pr create", start: 10 * M + 51 * S, end: 11 * M + 39 * S, status: "done", output: "https://github.com/acme/web/pull/482", }, { id: "summary", name: "Summarize the run", kind: "llm", model: "claude-opus-5-5", start: 11 * M + 40 * S, end: 11 * M + 52 * S, status: "done", tokens: { input: 26_900, output: 4_960 }, cost: 0.15, }, ], }; function traceAt(span: TraceSpan, t: number): TraceSpan | null { if (span.start > t) return null; const finished = span.end != null && span.end <= t; return { ...span, end: finished ? span.end : undefined, status: finished ? span.status : "running", output: finished ? span.output : undefined, error: finished ? span.error : undefined, tokens: finished ? span.tokens : undefined, cost: finished ? span.cost : undefined, children: span.children?.map((c) => traceAt(c, t)).filter((c): c is TraceSpan => c != null), }; } const FROM = 4 * M + 40 * S; const SPEED = 75; const S = 1000; const M = 60_000; export function TraceWaterfallFull() { const [t, setT] = React.useState(FROM); const [run, setRun] = React.useState(0); const end = RUN.end ?? 0; // biome-ignore lint/correctness/useExhaustiveDependencies: `run` replays the trace React.useEffect(() => { const began = Date.now(); setT(FROM); const id = setInterval(() => { const next = Math.min(end, FROM + (Date.now() - began) * SPEED); setT(next); if (next >= end) clearInterval(id); }, 120); return () => clearInterval(id); }, [run]); const root = traceAt(RUN, t); return ( <TraceWaterfall className="w-full max-w-3xl" title="Trace" spans={root ? [root] : []} now={t} defaultSelectedId="test-1" defaultCollapsedIds={["explorer"]} actions={ <IconButton label="Replay" icon={<RotateCcw />} variant="ghost" size="xs" className="-mr-1.5" onClick={() => setRun((r) => r + 1)} /> } /> ); } ``` ### Live, from a wall clock (state) A subagent that is still running: `startedAt` makes running bars grow in real time. ```tsx "use client"; import * as React from "react"; import { TraceWaterfall } from "@kura-ui/react/trace-waterfall"; export function TraceWaterfallLive() { const [startedAt] = React.useState(() => Date.now() - 38_000); return ( <TraceWaterfall className="w-full max-w-2xl" title="test-writer" startedAt={startedAt} spans={[ { id: "tw", name: "test-writer", kind: "agent", meta: "subagent", start: 0, status: "running", children: [ { id: "tw-read", name: "read_file", kind: "tool", meta: "src/auth/login.test.ts", start: 400, end: 900, status: "done", }, { id: "tw-ctx", name: "search_code", kind: "retrieval", meta: "refreshSession", start: 1_000, end: 2_600, status: "done", }, { id: "tw-llm", name: "Write session tests", kind: "llm", start: 2_800, end: 24_100, status: "done", tokens: { input: 31_200, output: 2_870 }, cost: 0.14, }, { id: "tw-approve", name: "edit_file", kind: "tool", meta: "src/auth/session.test.ts", start: 24_300, end: 25_000, status: "done", }, { id: "tw-run", name: "bash", kind: "tool", meta: "pnpm vitest session", start: 25_200, status: "running", }, ], }, ]} /> ); } ``` ### Custom details (composition) `renderDetails` shows the edit a tool made as a CodeBlock. ```tsx import { CodeBlock } from "@kura-ui/react/code-block"; import { TraceWaterfall } from "@kura-ui/react/trace-waterfall"; export function TraceWaterfallCustomDetails() { return ( <TraceWaterfall className="w-full max-w-2xl" title="Tool calls" defaultSelectedId="edit" spans={[ { id: "turn", name: "Fix token refresh", kind: "agent", start: 0, end: 9_300, status: "done", children: [ { id: "think", name: "Diagnose the failure", kind: "llm", start: 0, end: 7_900, status: "done", tokens: { input: 71_500, output: 4_800 }, cost: 0.29, }, { id: "edit", name: "edit_file", kind: "tool", meta: "src/auth/client.ts", start: 8_000, end: 8_400, status: "done", }, { id: "test", name: "bash", kind: "tool", meta: "pnpm test login", start: 8_500, end: 9_300, status: "done", }, ], }, ]} renderDetails={(span) => span.id === "edit" ? ( <CodeBlock language="ts" filename="src/auth/client.ts" code={`if (res.status === 401 && session.refreshToken) {\n session = await auth.refresh(session.refreshToken)\n return retry(req, session)\n}`} /> ) : null } /> ); } ``` ## Dependencies - npm: `lucide-react` - Kura registry items: `kura-theme`, `kura-format`, `status-glyph`, `use-controllable-state`, `use-elapsed`, `utils` - Related: `task-list`, `agent-fleet`, `run-header`, `tool-call`, `agent-timeline` --- # 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 blue accent 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 /> ``` ### useElapsed Live elapsed time since a start instant while something is running, frozen when it stops. SSR-safe (null until mounted). ```ts import { useElapsed } from "@kura-ui/react/hooks"; useElapsed(since: Date | number | null | undefined, running: boolean, interval?: number): number | null ``` Returns: Milliseconds since `since`, or null before mount or without a start time. ```tsx const ms = useElapsed(run.startedAt, run.status === "running"); <span>{ms == null ? "—" : formatClock(ms)}</span> ``` --- # 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 (blue "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 — true greys (no tint), Geist-like steps | Step | Use | Light | Dark | | --------- | ------------------------- | ------------------ | ------------------ | | `gray-1` | app canvas | `oklch(0.99 0 0)` | `oklch(0.145 0 0)` | | `gray-2` | subtle / sunken bg | `oklch(0.975 0 0)` | `oklch(0.17 0 0)` | | `gray-3` | UI element bg | `oklch(0.96 0 0)` | `oklch(0.2 0 0)` | | `gray-4` | hovered element bg | `oklch(0.94 0 0)` | `oklch(0.225 0 0)` | | `gray-5` | active element bg | `oklch(0.92 0 0)` | `oklch(0.25 0 0)` | | `gray-6` | subtle borders | `oklch(0.895 0 0)` | `oklch(0.28 0 0)` | | `gray-7` | borders | `oklch(0.86 0 0)` | `oklch(0.33 0 0)` | | `gray-8` | strong borders | `oklch(0.79 0 0)` | `oklch(0.41 0 0)` | | `gray-9` | solid | `oklch(0.64 0 0)` | `oklch(0.55 0 0)` | | `gray-10` | placeholder / subtle text | `oklch(0.58 0 0)` | `oklch(0.62 0 0)` | | `gray-11` | muted text (≥ 4.5:1) | `oklch(0.46 0 0)` | `oklch(0.74 0 0)` | | `gray-12` | primary text, ink | `oklch(0.16 0 0)` | `oklch(0.97 0 0)` | Cards are white on a near-white canvas in light, and one step lighter than a near-black canvas in dark. ### 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" (blue, hue ~260) Light `oklch(0.56 0.2 260)`, dark `oklch(0.68 0.17 258)`. 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). - No ornaments: no textures, glows, glassmorphism on chrome, serif/italic display type or brush marks. Taste comes from typography, spacing, contrast and motion, not decoration. --- ## 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.

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

 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"`) — Blue “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  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 (
    
  );
}
```

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

Description, details, controlled decision, Always allow, custom labels and ⌘↵ / Esc; “Ask again” resets it.

```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("pending");
  return (
    
      
            Working directory: ~/code/kura-ui
            Requested by step 3 of 5, “Rebuild the docs”
            Not tracked by git — cannot be restored from history
          
        }
        decision={decision}
        onDecisionChange={setDecision}
        onAlwaysAllow={() => {}}
        shortcuts
        approveLabel="Run anyway"
        denyLabel="Deny"
        alwaysAllowLabel="Always allow"
      />
      {decision !== "pending" && (
        
      )}
    
  );
}
```

### 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 (
    
      
      
       {}}
        shortcuts={false}
      />
    
  );
}
```

### 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("pending");
  return (
    
      }
        status={
          decision === "pending" ? "awaiting-approval" : decision === "denied" ? "error" : "success"
        }
        error={decision === "denied" ? "Denied by user." : undefined}
        duration={decision === "approved" ? 240 : undefined}
        summary="+2 −1"
      />
      }
        risk="low"
        decision={decision}
        onDecisionChange={setDecision}
        shortcuts={false}
        approveLabel="Apply"
        details={}
      />
    
  );
}
```

## 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 , 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 , 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 “, <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, Pencil } 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>
        }
      />
      <Button
        size="xs"
        variant="ghost"
        className="self-end"
        disabled={busy}
        onClick={() => {
          setRun((r) => r + 1);
          setVersion(run + 2);
        }}
      >
        <Pencil />
        Ask for an edit
      </Button>
    </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 blue accent (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}
          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`

---

# Browser Session

> A computer/browser-use session made legible: tidy browser frame, the page, the agent's cursor with click ripple and target box, and a step log with take-over.

- **Slug:** `browser-session` · **Category:** workspace · **Status:** experimental
- **Import:** `import { BrowserHighlight, BrowserPoint, BrowserSession, BrowserStep, BrowserStepKind } from "@kura-ui/react/browser-session";`
- **Docs:** https://kuro.abstergo.fyi/components/browser-session
- **Registry item:** https://kuro.abstergo.fyi/r/browser-session.json
- **Tags:** agent, browser, computer-use, browser-use, operator, cursor, screenshot, takeover

## Install

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

## When to use

- Show what a browser-use or computer-use agent is doing on a web page (Operator, Claude computer use, Browserbase, Playwright-driven agents).
- Stream screenshots of a remote browser (`src`) with the agent's next action drawn on top (`cursor`, `highlight`).
- Replay a recorded browser run step by step with the log of navigate / click / type / scroll / extract actions.
- Hand control to the human when the agent hits a login, 2FA or CAPTCHA (`status="paused"` + `onResume`), or let them take over (`onTakeOver`).

## When not to use

- Terminal or shell output from the agent — use terminal.
- Code edits made by the agent — use diff-view or file-changes.
- A plan or todo list of the whole run — use task-list.
- A static rendered artifact (HTML preview, document) — use artifact-card.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `url` | `string` | — | yes | Page URL in the address bar. The host is emphasised, the path muted; https shows a lock. |
| `title` | `string` | — | no | Page title next to the address bar (hidden in narrow containers). |
| `children` | `React.ReactNode` | — | no | Viewport content: a live page, or a mock rendered as markup. |
| `src` | `string` | — | no | A screenshot URL to show instead of children (e.g. the latest frame from a remote browser). |
| `alt` | `string` | — | no | Alt text for `src`. Default “Screenshot of {url}”. |
| `viewport` | `{ width: number; height: number }` | — | no | Design size of the page in CSS px (e.g. the agent's 1280×800 screen). Children render at this size and scale to fit the frame, so % coordinates stay exact at any width. Omit to let children flow at the frame's width. |
| `aspectRatio` | `number` | `16 / 10` | no | Viewport aspect ratio when `viewport` is not given. |
| `scrollTop` | `number` | `0` | no | Vertical page scroll in viewport px; eases on change (use for scroll steps). |
| `cursor` | `BrowserPoint \| null` | — | no | The agent's cursor { x, y } in % of the viewport. Glides to new positions. |
| `cursorLabel` | `string` | — | no | Name tag on the cursor, e.g. the agent's name. |
| `clickKey` | `string \| number` | — | no | Change it to play a click ripple at the cursor. Default: the active step's id when that step is a click. |
| `highlight` | `BrowserHighlight \| null` | — | no | Box around the target element: { x, y, width, height } in % plus an optional `label` tag (e.g. `button "Create pull request"`). |
| `steps` | `readonly BrowserStep[]` | — | no | The action log. BrowserStep = { id, kind: "navigate" \| "click" \| "type" \| "scroll" \| "extract", label, status: AgentStatus, detail? (mono: URL, selector, typed text) }. Omit to hide the log. |
| `activeStep` | `string` | — | no | Id of the step being executed. Default: the first running step. |
| `status` | `"browsing" \| "paused" \| "done" \| "failed"` | `"browsing"` | no | browsing = “Agent is browsing” (blue, shimmer); paused = “Paused for you” (amber, the viewport gets an amber edge); done; failed. |
| `statusText` | `React.ReactNode` | — | no | Secondary text after the status, e.g. “Enter the 2FA code, then hand back”. |
| `startedAt` | `Date \| number` | — | no | Session start (wall clock) for the elapsed clock; ticks while browsing. |
| `loading` | `boolean` | — | no | Show the loading bar under the address bar. Default: true while the active step is a running navigate. |
| `actions` | `React.ReactNode` | — | no | Extra controls in the status line (e.g. open in new tab, replay). |
| `onTakeOver` | `() => void` | — | no | Shows a “Take over” button while browsing. |
| `onResume` | `() => void` | — | no | Shows a “Resume agent” button while paused. |
| `layout` | `"auto" \| "side" \| "stacked"` | `"auto"` | no | Step log beside the browser (side), below it (stacked), or beside only when the container is ≥ 48rem (auto). |

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

## Anatomy

- **BrowserSession** (`data-slot="browser-session"`) — Root panel; `data-status`, `data-layout`; container-query context; polite status region.
- **Header** (`data-slot="browser-session-header"`) — Status line: glyph, “Agent is browsing” / “Paused for you”, statusText, done/total, elapsed, actions, Take over / Resume.
- **Elapsed** (`data-slot="browser-session-elapsed"`) — Mono clock from startedAt.
- **Browser** (`data-slot="browser-session-browser"`) — Column with the chrome and the viewport.
- **Chrome** (`data-slot="browser-session-chrome"`) — Title (favicon letter + text) and the address bar.
- **Address** (`data-slot="browser-session-address"`) — role="group" “Address”: lock, host, muted path, in mono.
- **Loading** (`data-slot="browser-session-loading"`) — 2px accent sweep under the chrome while a page loads.
- **Viewport** (`data-slot="browser-session-viewport"`) — Fixed-aspect frame (no layout shift); amber inner edge while paused.
- **Page** (`data-slot="browser-session-page"`) — Holds children/src; scaled to fit when `viewport` is set; translated by scrollTop.
- **Overlay** (`data-slot="browser-session-overlay"`) — aria-hidden layer for the highlight, ripple and cursor.
- **Highlight** (`data-slot="browser-session-highlight"`) — Accent box + mono tag around the target; eases between targets.
- **Cursor** (`data-slot="browser-session-cursor"`) — Pointer arrow with an optional accent name tag; glides between points.
- **Ripple** (`data-slot="browser-session-ripple"`) — Accent ring that expands and fades after the cursor arrives.
- **Log** (`data-slot="browser-session-log"`) — Scrollable step log; keeps the active step in view.
- **Step** (`data-slot="browser-session-step"`) — <li> with `data-kind`, `data-status`, `data-active`; aria-current="step" on the active one.

## Accessibility

- The overlay (cursor, ripple, highlight) is decorative and aria-hidden; what the agent is doing is carried by the step log and the status line.
- The step log is an <ol> labelled “Browser actions”; each step speaks its status after the label, and the active one has aria-current="step".
- A polite status region announces the active step's label (when it is a string), “Paused for you” / your statusText, “Session ended” or “Session failed” — never the ticking clock.
- The address bar is a labelled group; the lock icon is labelled “Secure connection”. With `src`, the image gets alt text (default “Screenshot of {url}”).
- Take over / Resume agent are real buttons with visible focus. Paused state is signalled by text and glyph, not only the amber edge.
- Reduced motion: The cursor and highlight jump instead of gliding (the highlight still fades), the click ripple is skipped, page scroll is instant, the loading sweep becomes a static bar and the shimmer stops.

| Keys | Action |
| --- | --- |
| Tab | Moves to the status-line actions (Take over / Resume agent) and any controls inside the page. |

## Notes for agents

- Coordinates are percentages of the viewport. If your agent reports pixels on a W×H screen, pass `viewport={{ width: W, height: H }}` and use x = px / W * 100.
- For remote browsers pass the latest screenshot as `src` and keep `viewport` equal to the screenshot size; draw the *next* action with `cursor` + `highlight`.
- Change `clickKey` (e.g. an action counter) to replay the ripple; repeated clicks on the same step otherwise only ripple once.
- Set `status="paused"` whenever the agent needs the human (login, 2FA, CAPTCHA, payment) and say why in `statusText`.
- Map the agent's actions to the five kinds; put the URL, selector or typed text in `detail` (mono).

## Examples

### A page with the agent's cursor (minimal)

A mock PR page at a fixed 800×500 design size, the cursor and a target box.

```tsx
import { Check, GitPullRequest } from "lucide-react";
import { BrowserSession } from "@kura-ui/react/browser-session";

const W = 800;

const H = 500;

const at = (x: number, y: number) => ({ x: (x / W) * 100, y: (y / H) * 100 });

const box = (x: number, y: number, w: number, h: number, label?: string) => ({
  x: (x / W) * 100,
  y: (y / H) * 100,
  width: (w / W) * 100,
  height: (h / H) * 100,
  label,
});

function PullRequestPage() {
  return (
    <div className="h-[500px] bg-kura-surface font-kura-sans text-kura-fg">
      <SiteBar />
      <div className="px-8 pt-6">
        <h1 data-target="pr-h1" className="font-semibold text-[20px] leading-7 tracking-[-0.015em]">
          {PR_TITLE} <span className="font-normal text-kura-fg-subtle">#482</span>
        </h1>
        <div className="mt-2 flex items-center gap-2 text-[13px] text-kura-fg-muted">
          <span className="flex items-center gap-1 rounded-full bg-kura-success/15 px-2 py-0.5 font-medium text-[12px] text-kura-success-text">
            <GitPullRequest className="size-3" strokeWidth={2} /> Open
          </span>
          <span>
            <span className="font-medium text-kura-fg">kura</span> wants to merge 4 commits into{" "}
            <span className="font-kura-mono text-[12px]">main</span> from{" "}
            <span className="font-kura-mono text-[12px]">kura/auth-client</span>
          </span>
        </div>
        <div className="mt-4 flex gap-5 border-kura-border-subtle border-b text-[13px] text-kura-fg-muted">
          <span className="-mb-px border-kura-fg border-b-2 pb-2 font-medium text-kura-fg">
            Conversation
          </span>
          <span>Commits 4</span>
          <span>Checks 3</span>
          <span>Files changed 6</span>
        </div>
        <div className="mt-4 rounded-[10px] p-4 text-[13px] text-kura-fg-muted leading-5 shadow-kura-xs">
          {PR_BODY}
        </div>
        <div className="mt-3 flex flex-col rounded-[10px] text-[13px] shadow-kura-xs">
          <div className="flex h-10 items-center gap-2 border-kura-border-subtle border-b px-4 font-medium">
            <Check className="size-4 text-kura-success" strokeWidth={2.25} /> All checks have passed
          </div>
          {[
            ["test", "142 passed · 41s"],
            ["typecheck", "0 errors · 18s"],
            ["lint", "clean · 6s"],
          ].map(([name, meta]) => (
            <div key={name} className="flex h-9 items-center gap-2 px-4">
              <Check className="size-3.5 text-kura-success" strokeWidth={2.25} />
              <span className="font-kura-mono text-[12.5px]">{name}</span>
              <span className="ml-auto font-kura-mono text-[12px] text-kura-fg-subtle">{meta}</span>
            </div>
          ))}
        </div>
      </div>
    </div>
  );
}

const PR_TITLE = "Migrate session API to @acme/auth client";

const PR_BODY =
  "Replaces fetchUser() and the legacy /api/session REST calls with createAuthClient(). Refreshes expired sessions with the rotated token.";

function SiteBar() {
  return (
    <div className="flex h-12 items-center gap-3 border-kura-border-subtle border-b px-8 text-[14px]">
      <span className="size-5 rounded-[5px] bg-kura-fg" />
      <span className="text-kura-fg-muted">acme</span>
      <span className="text-kura-fg-subtle">/</span>
      <span className="font-semibold">web</span>
      <span className="ml-auto flex items-center gap-5 text-[13px] text-kura-fg-muted">
        <span>Code</span>
        <span className="font-medium text-kura-fg">Pull requests</span>
        <span>Actions</span>
        <span className="size-6 rounded-full bg-kura-gray-5" />
      </span>
    </div>
  );
}

export function BrowserSessionMinimal() {
  return (
    <BrowserSession
      className="w-full max-w-xl"
      url="https://github.com/acme/web/pull/482"
      title="Migrate session API · acme/web"
      viewport={{ width: W, height: H }}
      cursor={at(468, 94)}
      highlight={box(24, 66, 478, 40, "h1")}
    >
      <PullRequestPage />
    </BrowserSession>
  );
}
```

### Opening the pull request (full)

Kura opens the compare view, types the title and description, clicks “Create pull request” and reads the PR number. The cursor glides, clicks ripple, the log advances and the session settles.

```tsx
"use client";

import { Check, GitBranch, GitPullRequest, RotateCcw } from "lucide-react";
import * as React from "react";
import { IconButton } from "@kura-ui/react/icon-button";
import { BrowserSession, type BrowserStep } from "@kura-ui/react/browser-session";

const W = 800;

const H = 500;

const PR_TITLE = "Migrate session API to @acme/auth client";

const PR_BODY =
  "Replaces fetchUser() and the legacy /api/session REST calls with createAuthClient(). Refreshes expired sessions with the rotated token.";

function ComparePage({
  title,
  body,
  focus,
}: {
  title: string;
  body: string;
  focus: "title" | "body" | null;
}) {
  return (
    <div className="h-[500px] bg-kura-surface font-kura-sans text-kura-fg">
      <SiteBar />
      <div className="px-8 pt-6">
        <h1 className="font-semibold text-[20px] leading-7 tracking-[-0.015em]">
          Open a pull request
        </h1>
        <p className="mt-1 text-[13px] text-kura-fg-muted leading-5">
          Create a new pull request by comparing changes across two branches.
        </p>
        <div className="mt-4 flex h-10 items-center gap-2 rounded-[8px] bg-kura-surface-sunken px-3 text-[12.5px]">
          <GitBranch className="size-3.5 text-kura-fg-subtle" strokeWidth={1.75} />
          <span className="rounded-[5px] bg-kura-surface px-1.5 py-0.5 font-kura-mono shadow-kura-xs">
            base: main
          </span>
          <span className="text-kura-fg-subtle">←</span>
          <span className="rounded-[5px] bg-kura-surface px-1.5 py-0.5 font-kura-mono shadow-kura-xs">
            compare: kura/auth-client
          </span>
          <span className="ml-auto flex items-center gap-1 font-medium text-kura-success-text">
            <Check className="size-3.5" strokeWidth={2.25} /> Able to merge
          </span>
        </div>
        <div className="mt-4 flex flex-col gap-1.5 rounded-[10px] p-4 shadow-kura-xs">
          <span className="font-medium text-[12.5px] leading-[18px]">Title</span>
          <Field value={title} focused={focus === "title"} />
          <span className="mt-1.5 font-medium text-[12.5px] leading-[18px]">Description</span>
          <Field value={body} focused={focus === "body"} tall />
          <div className="mt-1.5 flex h-8 items-center justify-between">
            <span className="text-[12px] text-kura-fg-subtle">Markdown is supported</span>
            <span
              data-target="submit"
              className="flex h-8 w-[160px] items-center justify-center rounded-[7px] bg-kura-ink font-medium text-[13px] text-kura-fg-inverted"
            >
              Create pull request
            </span>
          </div>
        </div>
        <p className="mt-3 font-kura-mono text-[12px] text-kura-fg-subtle">
          4 commits · 6 files changed · +142 −38
        </p>
      </div>
    </div>
  );
}

function PullRequestPage() {
  return (
    <div className="h-[500px] bg-kura-surface font-kura-sans text-kura-fg">
      <SiteBar />
      <div className="px-8 pt-6">
        <h1 data-target="pr-h1" className="font-semibold text-[20px] leading-7 tracking-[-0.015em]">
          {PR_TITLE} <span className="font-normal text-kura-fg-subtle">#482</span>
        </h1>
        <div className="mt-2 flex items-center gap-2 text-[13px] text-kura-fg-muted">
          <span className="flex items-center gap-1 rounded-full bg-kura-success/15 px-2 py-0.5 font-medium text-[12px] text-kura-success-text">
            <GitPullRequest className="size-3" strokeWidth={2} /> Open
          </span>
          <span>
            <span className="font-medium text-kura-fg">kura</span> wants to merge 4 commits into{" "}
            <span className="font-kura-mono text-[12px]">main</span> from{" "}
            <span className="font-kura-mono text-[12px]">kura/auth-client</span>
          </span>
        </div>
        <div className="mt-4 flex gap-5 border-kura-border-subtle border-b text-[13px] text-kura-fg-muted">
          <span className="-mb-px border-kura-fg border-b-2 pb-2 font-medium text-kura-fg">
            Conversation
          </span>
          <span>Commits 4</span>
          <span>Checks 3</span>
          <span>Files changed 6</span>
        </div>
        <div className="mt-4 rounded-[10px] p-4 text-[13px] text-kura-fg-muted leading-5 shadow-kura-xs">
          {PR_BODY}
        </div>
        <div className="mt-3 flex flex-col rounded-[10px] text-[13px] shadow-kura-xs">
          <div className="flex h-10 items-center gap-2 border-kura-border-subtle border-b px-4 font-medium">
            <Check className="size-4 text-kura-success" strokeWidth={2.25} /> All checks have passed
          </div>
          {[
            ["test", "142 passed · 41s"],
            ["typecheck", "0 errors · 18s"],
            ["lint", "clean · 6s"],
          ].map(([name, meta]) => (
            <div key={name} className="flex h-9 items-center gap-2 px-4">
              <Check className="size-3.5 text-kura-success" strokeWidth={2.25} />
              <span className="font-kura-mono text-[12.5px]">{name}</span>
              <span className="ml-auto font-kura-mono text-[12px] text-kura-fg-subtle">{meta}</span>
            </div>
          ))}
        </div>
      </div>
    </div>
  );
}

const COMPARE_URL = "https://github.com/acme/web/compare/main...kura/auth-client";

const PR_URL = "https://github.com/acme/web/pull/482";

const STEPS: Omit<BrowserStep, "status">[] = [
  { id: "open", kind: "navigate", label: "Open the compare view", detail: COMPARE_URL.slice(8) },
  { id: "focus", kind: "click", label: "Focus the title field", detail: "input#pr-title" },
  { id: "title", kind: "type", label: "Type the PR title", detail: `“${PR_TITLE}”` },
  {
    id: "body",
    kind: "type",
    label: "Write the description",
    detail: `“${PR_BODY.slice(0, 48)}…”`,
  },
  {
    id: "submit",
    kind: "click",
    label: "Click “Create pull request”",
    detail: "button[type=submit]",
  },
  { id: "read", kind: "extract", label: "Read the PR number", detail: "#482 · Open" },
];

const TARGETS = {
  open: { cursor: at(400, 300), highlight: null },
  focus: { cursor: at(140, 256), highlight: box(48, 236, 704, 36, "input#pr-title") },
  title: { cursor: at(140, 256), highlight: box(48, 236, 704, 36, "input#pr-title") },
  body: { cursor: at(160, 330), highlight: box(48, 308, 704, 96, "textarea#pr-body") },
  submit: {
    cursor: at(690, 434),
    highlight: box(592, 416, 160, 32, 'button "Create pull request"'),
  },
  read: { cursor: at(468, 94), highlight: box(24, 66, 478, 40, "h1 · #482") },
} as const;

const at = (x: number, y: number) => ({ x: (x / W) * 100, y: (y / H) * 100 });

const box = (x: number, y: number, w: number, h: number, label?: string) => ({
  x: (x / W) * 100,
  y: (y / H) * 100,
  width: (w / W) * 100,
  height: (h / H) * 100,
  label,
});

function SiteBar() {
  return (
    <div className="flex h-12 items-center gap-3 border-kura-border-subtle border-b px-8 text-[14px]">
      <span className="size-5 rounded-[5px] bg-kura-fg" />
      <span className="text-kura-fg-muted">acme</span>
      <span className="text-kura-fg-subtle">/</span>
      <span className="font-semibold">web</span>
      <span className="ml-auto flex items-center gap-5 text-[13px] text-kura-fg-muted">
        <span>Code</span>
        <span className="font-medium text-kura-fg">Pull requests</span>
        <span>Actions</span>
        <span className="size-6 rounded-full bg-kura-gray-5" />
      </span>
    </div>
  );
}

function Field({ value, focused, tall }: { value: string; focused: boolean; tall?: boolean }) {
  return (
    <div
      data-target={tall ? "body" : "title"}
      className={
        tall
          ? "h-24 rounded-[7px] bg-kura-surface px-3 py-2 text-[13px] leading-5"
          : "flex h-9 items-center rounded-[7px] bg-kura-surface px-3 text-[13.5px]"
      }
      style={{
        boxShadow: focused
          ? "0 0 0 1px var(--kura-accent), 0 0 0 3px var(--kura-ring)"
          : "0 0 0 1px var(--kura-border-strong)",
      }}
    >
      <span>{value}</span>
      {focused && (
        <span className="ml-px inline-block h-4 w-px translate-y-[3px] animate-kura-pulse bg-kura-fg" />
      )}
      {!value && !focused && (
        <span className="text-kura-fg-subtle">{tall ? "Add a description" : "Title"}</span>
      )}
    </div>
  );
}

export function BrowserSessionFull() {
  const [step, setStep] = React.useState(0);
  const [typed, setTyped] = React.useState({ title: 0, body: 0 });
  const [clicks, setClicks] = React.useState(0);
  const [run, setRun] = React.useState(0);
  const [startedAt, setStartedAt] = React.useState<number>();

  // biome-ignore lint/correctness/useExhaustiveDependencies: `run` replays the session
  React.useEffect(() => {
    setStep(0);
    setTyped({ title: 0, body: 0 });
    setStartedAt(Date.now() - 6 * 60_000 - 12_000);
    const timers: ReturnType<typeof setTimeout>[] = [];
    const later = (ms: number, fn: () => void) => timers.push(setTimeout(fn, ms));
    const type = (from: number, ms: number, key: "title" | "body", total: number) => {
      const n = 24;
      for (let i = 1; i <= n; i++)
        later(from + (ms / n) * i, () =>
          setTyped((t) => ({ ...t, [key]: Math.round((total * i) / n) })),
        );
    };
    later(1300, () => setStep(1));
    later(2300, () => setStep(2));
    type(2400, 1500, "title", PR_TITLE.length);
    later(4100, () => {
      setStep(3);
      setClicks((c) => c + 1);
    });
    type(4600, 1600, "body", PR_BODY.length);
    later(6500, () => setStep(4));
    later(7700, () => setStep(5));
    later(9200, () => setStep(6));
    return () => timers.forEach(clearTimeout);
  }, [run]);

  const created = step >= 5;
  const current = STEPS[step];
  const target = current ? TARGETS[current.id as keyof typeof TARGETS] : TARGETS.read;
  const steps: BrowserStep[] = STEPS.map((s, i) => ({
    ...s,
    status: i < step ? "done" : i === step ? "running" : "queued",
  }));

  return (
    <BrowserSession
      className="w-full max-w-4xl"
      url={created ? PR_URL : COMPARE_URL}
      title={created ? "Migrate session API · acme/web" : "Open a pull request · acme/web"}
      viewport={{ width: W, height: H }}
      status={step >= STEPS.length ? "done" : "browsing"}
      startedAt={startedAt}
      steps={steps}
      cursor={target.cursor}
      cursorLabel="Kura"
      clickKey={`${run}-${clicks}-${current?.kind === "click" ? current.id : ""}`}
      highlight={step >= STEPS.length ? null : target.highlight}
      onTakeOver={() => {}}
      statusText={step >= STEPS.length ? "acme/web#482 opened" : undefined}
      actions={
        step >= STEPS.length && (
          <IconButton
            label="Replay"
            icon={<RotateCcw />}
            variant="ghost"
            size="xs"
            className="animate-kura-fade-in"
            onClick={() => setRun((r) => r + 1)}
          />
        )
      }
    >
      <div className={step === 0 ? "opacity-40 transition-opacity" : "transition-opacity"}>
        {created ? (
          <PullRequestPage />
        ) : (
          <ComparePage
            title={PR_TITLE.slice(0, typed.title)}
            body={PR_BODY.slice(0, typed.body)}
            focus={step === 1 || step === 2 ? "title" : step === 3 ? "body" : null}
          />
        )}
      </div>
    </BrowserSession>
  );
}
```

### Paused for you (state)

A 2FA prompt only the human can answer: amber edge, “Resume agent”.

```tsx
"use client";

import { Check } from "lucide-react";
import * as React from "react";
import { BrowserSession } from "@kura-ui/react/browser-session";

const W = 800;

const H = 500;

const at = (x: number, y: number) => ({ x: (x / W) * 100, y: (y / H) * 100 });

const box = (x: number, y: number, w: number, h: number, label?: string) => ({
  x: (x / W) * 100,
  y: (y / H) * 100,
  width: (w / W) * 100,
  height: (h / H) * 100,
  label,
});

function TwoFactorPage() {
  return (
    <div className="flex h-[500px] flex-col items-center bg-kura-surface-sunken pt-16 font-kura-sans text-kura-fg">
      <div className="flex w-[360px] flex-col items-center gap-1 rounded-[14px] bg-kura-surface px-8 py-7 shadow-kura-sm">
        <span className="mb-3 size-8 rounded-[8px] bg-kura-fg" />
        <h1 className="font-semibold text-[17px] tracking-[-0.01em]">Two-factor authentication</h1>
        <p className="text-center text-[13px] text-kura-fg-muted leading-5">
          Enter the 6-digit code from your authenticator app to continue to Acme Cloud.
        </p>
        <div data-target="otp" className="mt-5 flex gap-2">
          {[0, 1, 2, 3, 4, 5].map((i) => (
            <span
              key={i}
              className="h-11 w-9 rounded-[8px] bg-kura-surface"
              style={{
                boxShadow:
                  i === 0
                    ? "0 0 0 1px var(--kura-accent), 0 0 0 3px var(--kura-ring)"
                    : "0 0 0 1px var(--kura-border-strong)",
              }}
            />
          ))}
        </div>
        <span className="mt-5 flex h-9 w-full items-center justify-center rounded-[8px] bg-kura-ink font-medium text-[13px] text-kura-fg-inverted">
          Verify
        </span>
        <span className="mt-3 text-[12px] text-kura-fg-subtle">Use a recovery code instead</span>
      </div>
    </div>
  );
}

export function BrowserSessionPaused() {
  const [paused, setPaused] = React.useState(true);
  const [startedAt] = React.useState(() => Date.now() - 9 * 60_000 - 41_000);
  return (
    <BrowserSession
      className="w-full max-w-4xl"
      url="https://cloud.acme.dev/login/two-factor?next=%2Fweb%2Fdeployments"
      title="Sign in · Acme Cloud"
      viewport={{ width: W, height: H }}
      status={paused ? "paused" : "browsing"}
      statusText={paused ? "Enter the 2FA code, then hand back" : undefined}
      startedAt={startedAt}
      cursor={at(300, 262)}
      cursorLabel="Kura"
      highlight={box(264, 226, 272, 58, "input[autocomplete=one-time-code]")}
      onResume={() => setPaused(false)}
      onTakeOver={() => setPaused(true)}
      steps={[
        {
          id: "1",
          kind: "navigate",
          label: "Open the preview",
          status: "done",
          detail: "cloud.acme.dev/web/deployments",
        },
        {
          id: "2",
          kind: "click",
          label: "Continue with GitHub",
          status: "done",
          detail: 'button[data-provider="github"]',
        },
        {
          id: "3",
          kind: "type",
          label: "Enter the 2FA code",
          status: paused ? "waiting" : "running",
          detail: "Needs a code only you have",
        },
        {
          id: "4",
          kind: "extract",
          label: "Check the login page",
          status: "queued",
          detail: "/login",
        },
      ]}
    >
      <TwoFactorPage />
    </BrowserSession>
  );
}
```

### Under the plan (composition)

A narrow stacked session under a TaskList, as in a run sidebar.

```tsx
import { Check, GitPullRequest } from "lucide-react";
import { TaskList } from "@kura-ui/react/task-list";
import { BrowserSession } from "@kura-ui/react/browser-session";

const W = 800;

const H = 500;

const at = (x: number, y: number) => ({ x: (x / W) * 100, y: (y / H) * 100 });

const box = (x: number, y: number, w: number, h: number, label?: string) => ({
  x: (x / W) * 100,
  y: (y / H) * 100,
  width: (w / W) * 100,
  height: (h / H) * 100,
  label,
});

function PullRequestPage() {
  return (
    <div className="h-[500px] bg-kura-surface font-kura-sans text-kura-fg">
      <SiteBar />
      <div className="px-8 pt-6">
        <h1 data-target="pr-h1" className="font-semibold text-[20px] leading-7 tracking-[-0.015em]">
          {PR_TITLE} <span className="font-normal text-kura-fg-subtle">#482</span>
        </h1>
        <div className="mt-2 flex items-center gap-2 text-[13px] text-kura-fg-muted">
          <span className="flex items-center gap-1 rounded-full bg-kura-success/15 px-2 py-0.5 font-medium text-[12px] text-kura-success-text">
            <GitPullRequest className="size-3" strokeWidth={2} /> Open
          </span>
          <span>
            <span className="font-medium text-kura-fg">kura</span> wants to merge 4 commits into{" "}
            <span className="font-kura-mono text-[12px]">main</span> from{" "}
            <span className="font-kura-mono text-[12px]">kura/auth-client</span>
          </span>
        </div>
        <div className="mt-4 flex gap-5 border-kura-border-subtle border-b text-[13px] text-kura-fg-muted">
          <span className="-mb-px border-kura-fg border-b-2 pb-2 font-medium text-kura-fg">
            Conversation
          </span>
          <span>Commits 4</span>
          <span>Checks 3</span>
          <span>Files changed 6</span>
        </div>
        <div className="mt-4 rounded-[10px] p-4 text-[13px] text-kura-fg-muted leading-5 shadow-kura-xs">
          {PR_BODY}
        </div>
        <div className="mt-3 flex flex-col rounded-[10px] text-[13px] shadow-kura-xs">
          <div className="flex h-10 items-center gap-2 border-kura-border-subtle border-b px-4 font-medium">
            <Check className="size-4 text-kura-success" strokeWidth={2.25} /> All checks have passed
          </div>
          {[
            ["test", "142 passed · 41s"],
            ["typecheck", "0 errors · 18s"],
            ["lint", "clean · 6s"],
          ].map(([name, meta]) => (
            <div key={name} className="flex h-9 items-center gap-2 px-4">
              <Check className="size-3.5 text-kura-success" strokeWidth={2.25} />
              <span className="font-kura-mono text-[12.5px]">{name}</span>
              <span className="ml-auto font-kura-mono text-[12px] text-kura-fg-subtle">{meta}</span>
            </div>
          ))}
        </div>
      </div>
    </div>
  );
}

const PR_URL = "https://github.com/acme/web/pull/482";

const PR_TITLE = "Migrate session API to @acme/auth client";

const PR_BODY =
  "Replaces fetchUser() and the legacy /api/session REST calls with createAuthClient(). Refreshes expired sessions with the rotated token.";

function SiteBar() {
  return (
    <div className="flex h-12 items-center gap-3 border-kura-border-subtle border-b px-8 text-[14px]">
      <span className="size-5 rounded-[5px] bg-kura-fg" />
      <span className="text-kura-fg-muted">acme</span>
      <span className="text-kura-fg-subtle">/</span>
      <span className="font-semibold">web</span>
      <span className="ml-auto flex items-center gap-5 text-[13px] text-kura-fg-muted">
        <span>Code</span>
        <span className="font-medium text-kura-fg">Pull requests</span>
        <span>Actions</span>
        <span className="size-6 rounded-full bg-kura-gray-5" />
      </span>
    </div>
  );
}

export function BrowserSessionComposition() {
  return (
    <div className="flex w-full max-w-md flex-col gap-3">
      <TaskList
        title="Plan"
        collapseCompleted={false}
        items={[
          { id: "t", title: "Run pnpm test", status: "done", durationMs: 36_800 },
          { id: "p", title: "Open pull request", status: "running", detail: "via the browser" },
          { id: "s", title: "Summarize the run", status: "queued" },
        ]}
      />
      <BrowserSession
        layout="stacked"
        url={PR_URL}
        title="Migrate session API · acme/web"
        viewport={{ width: W, height: H }}
        cursor={at(468, 94)}
        cursorLabel="Kura"
        highlight={box(24, 66, 478, 40, "h1 · #482")}
        steps={[
          { id: "a", kind: "click", label: "Click “Create pull request”", status: "done" },
          {
            id: "b",
            kind: "extract",
            label: "Read the PR number",
            status: "running",
            detail: "h1",
          },
        ]}
      >
        <PullRequestPage />
      </BrowserSession>
    </div>
  );
}
```

## Dependencies

- npm: `lucide-react`
- Kura registry items: `kura-theme`, `button`, `kura-format`, `shimmer-text`, `status-glyph`, `use-elapsed`, `utils`
- Related: `terminal`, `task-list`, `run-header`, `approval-prompt`, `tool-call`

---

# 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 = solid ink call to action; secondary = soft grey fill; outline = surface with a hairline; ghost = no chrome until hover; 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.98 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 { GitBranch, Play, Plus, Trash2 } from "lucide-react";
import { Button } from "@kura-ui/react/button";

export function ButtonFull() {
  return (
    <div className="flex flex-col items-center gap-5">
      <div className="flex flex-wrap items-center justify-center gap-2">
        <Button variant="primary">Deploy</Button>
        <Button variant="secondary">Edit prompt</Button>
        <Button variant="outline">
          <GitBranch /> Branch chat
        </Button>
        <Button variant="ghost">Skip</Button>
        <Button variant="accent">
          <Play /> 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">
          <Plus /> Tag
        </Button>
        <Button size="sm" variant="outline">
          Small
        </Button>
        <Button size="md" variant="outline">
          Medium
        </Button>
        <Button size="lg" variant="outline">
          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 (
    <div className="flex items-center gap-2">
      <Button asChild>
        <a href="https://github.com/Absterrg0/Kura-UI#readme">Get started</a>
      </Button>
      <Button asChild variant="outline">
        <a href="https://github.com/Absterrg0/Kura-UI">
          View source <ArrowUpRight />
        </a>
      </Button>
    </div>
  );
}
```

## Dependencies

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

---

# Checkpoints

> Restore points across an agent run: a compact rail of auto and saved checkpoints with relative times, a current marker and inline-confirmed Restore.

- **Slug:** `checkpoints` · **Category:** agent · **Status:** experimental
- **Import:** `import { Checkpoint, Checkpoints } from "@kura-ui/react/checkpoints";`
- **Docs:** https://kuro.abstergo.fyi/components/checkpoints
- **Registry item:** https://kuro.abstergo.fyi/r/checkpoints.json
- **Tags:** agent, checkpoint, restore, rewind, undo, history, snapshot

## Install

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

## When to use

- A coding agent snapshots the workspace before edits (Claude Code rewind, Cursor checkpoints) and the human should be able to roll files back.
- Showing where the workspace is after a rewind: checkpoints newer than the current one read as undone and can be restored forward.
- Letting people save a manual checkpoint before a risky step (onCreate).

## When not to use

- The agent's plan or steps — use task-list or agent-timeline.
- Reviewing what changed in files — use diff-view or file-changes.
- Git history or commits — this is for harness snapshots, not a commit log.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `checkpoints` | `Checkpoint[]` | — | yes | { id, label, at, filesChanged?, kind: 'auto' \| 'manual', current? }, newest first. Mark exactly one current. |
| `title` | `React.ReactNode` | `"Checkpoints"` | no | Header title; the count follows it. |
| `onRestore` | `(id: string) => void \| Promise<void>` | — | no | Restore handler, called after the inline confirm. Return a promise to show a spinner until it settles. Without it no Restore buttons render. |
| `onCreate` | `() => void` | — | no | Shows 'Save checkpoint' in the header. Add a kind:'manual' checkpoint marked current. |
| `confirm` | `boolean` | `true` | no | Ask inline before restoring. false calls onRestore directly. |
| `empty` | `React.ReactNode` | — | no | Replaces the default empty state ('No checkpoints yet'). |

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

## Anatomy

- **Checkpoints** (`data-slot="checkpoints"`) — Root panel (a size container).
- **Header** (`data-slot="checkpoints-header"`) — Title, count and the optional checkpoints-create button.
- **Item** (`data-slot="checkpoints-item"`) — <li> with `data-kind`, `data-current`, `data-ahead` (newer than current = undone) and `data-state='confirming'`. Node on a hairline rail: hollow ring = auto, diamond = saved, ink dot with halo = current.
- **Label** (`data-slot="checkpoints-label"`) — What the agent had just done. Truncates.
- **Current** (`data-slot="checkpoints-current"`) — 'Current' pill.
- **Files** (`data-slot="checkpoints-files"`) — '3 files' in mono (hidden when narrow).
- **Restore** (`data-slot="checkpoints-restore"`) — Ghost button that swaps in for the relative time on hover/focus (always visible on touch); aria-expanded when confirming.
- **Confirm** (`data-slot="checkpoints-confirm"`) — Inline confirm under the row: what will be undone (or re-applied), Cancel and Restore.
- **Empty** (`data-slot="checkpoints-empty"`) — Empty state.

## Accessibility

- Role: `list (ol)`
- An ordered list labelled by the title. Times are <time datetime> with the absolute time as a tooltip.
- Restore buttons are named 'Restore to <label>'. Opening the confirm moves focus to its Restore button; Escape or Cancel closes it and returns focus to the trigger.
- Undone checkpoints carry visually hidden '(undone)'. A polite status region announces 'Restored to …'.
- Relative times render after mount only, so server and client markup match.
- Reduced motion: Rows fade in without rising; the confirm opens with a fade instead of a height transition.

| Keys | Action |
| --- | --- |
| Tab | Reach each Restore button (it becomes visible on focus) |
| Enter / Space | Open the inline confirm, then confirm |
| Escape | Cancel the confirm |

## Notes for agents

- Pass checkpoints newest first and mark exactly one current; the component uses `at` to work out which are undone.
- Restore only rewinds files in your harness; keep the conversation and say so in your UI copy if that differs.
- Make onRestore async when restoring takes time so the confirm shows a spinner and blocks double restores.

## Examples

### Three checkpoints (minimal)

```tsx
"use client";

import * as React from "react";
import { type Checkpoint, Checkpoints } from "@kura-ui/react/checkpoints";

const sec = (s: number) => Date.now() - s * 1000;

export function CheckpointsMinimal() {
  const [checkpoints] = React.useState<Checkpoint[]>(() => [
    {
      id: "c3",
      label: "Patched src/middleware.ts",
      at: sec(70),
      filesChanged: 1,
      kind: "auto",
      current: true,
    },
    {
      id: "c2",
      label: "Replaced fetchUser() in 9 files",
      at: sec(260),
      filesChanged: 9,
      kind: "auto",
    },
    { id: "c1", label: "Run started on kura/auth-client", at: sec(690), kind: "auto" },
  ]);
  return <Checkpoints className="w-full max-w-md" checkpoints={checkpoints} onRestore={() => {}} />;
}
```

### Live, with save and restore (full)

A new automatic checkpoint lands while you watch; Restore confirms inline and resolves after a simulated 900ms; Save checkpoint adds a manual one.

```tsx
"use client";

import * as React from "react";
import { type Checkpoint, Checkpoints } from "@kura-ui/react/checkpoints";

function storyline(): Checkpoint[] {
  return [
    {
      id: "tests",
      label: "Updated login and session tests",
      at: sec(150),
      filesChanged: 3,
      kind: "auto",
      current: true,
    },
    { id: "mw", label: "Patched src/middleware.ts", at: sec(290), filesChanged: 1, kind: "auto" },
    { id: "manual", label: "Before middleware changes", at: sec(370), kind: "manual" },
    {
      id: "client",
      label: "Replaced fetchUser() with auth.getSession()",
      at: sec(430),
      filesChanged: 9,
      kind: "auto",
    },
    { id: "start", label: "Run started on kura/auth-client", at: sec(720), kind: "auto" },
  ];
}

const sec = (s: number) => Date.now() - s * 1000;

export function CheckpointsFull() {
  const [checkpoints, setCheckpoints] = React.useState<Checkpoint[]>(storyline);

  // The agent keeps working: a new automatic checkpoint lands a moment after mount.
  React.useEffect(() => {
    const t = setTimeout(() => {
      setCheckpoints((list) => [
        {
          id: "fix",
          label: "Fixed expired-session refresh in src/auth/client.ts",
          at: Date.now(),
          filesChanged: 1,
          kind: "auto",
          current: true,
        },
        ...list.map((c) => ({ ...c, current: false })),
      ]);
    }, 1800);
    return () => clearTimeout(t);
  }, []);

  const restore = (id: string) =>
    new Promise<void>((resolve) =>
      setTimeout(() => {
        setCheckpoints((list) => list.map((c) => ({ ...c, current: c.id === id })));
        resolve();
      }, 900),
    );

  const save = () =>
    setCheckpoints((list) => {
      const current = list.find((c) => c.current);
      return [
        {
          id: `manual-${list.length}`,
          label: current ? `Saved after “${current.label}”` : "Saved checkpoint",
          at: Date.now(),
          kind: "manual" as const,
          current: true,
        },
        ...list.map((c) => ({ ...c, current: false })),
      ];
    });

  return (
    <Checkpoints
      className="w-full max-w-lg"
      checkpoints={checkpoints}
      onRestore={restore}
      onCreate={save}
    />
  );
}
```

### After a rewind (state)

The current checkpoint is in the middle; newer ones read as undone and can be restored forward.

```tsx
"use client";

import * as React from "react";
import { type Checkpoint, Checkpoints } from "@kura-ui/react/checkpoints";

function storyline(): Checkpoint[] {
  return [
    {
      id: "tests",
      label: "Updated login and session tests",
      at: sec(150),
      filesChanged: 3,
      kind: "auto",
      current: true,
    },
    { id: "mw", label: "Patched src/middleware.ts", at: sec(290), filesChanged: 1, kind: "auto" },
    { id: "manual", label: "Before middleware changes", at: sec(370), kind: "manual" },
    {
      id: "client",
      label: "Replaced fetchUser() with auth.getSession()",
      at: sec(430),
      filesChanged: 9,
      kind: "auto",
    },
    { id: "start", label: "Run started on kura/auth-client", at: sec(720), kind: "auto" },
  ];
}

const sec = (s: number) => Date.now() - s * 1000;

export function CheckpointsRestored() {
  const [checkpoints, setCheckpoints] = React.useState<Checkpoint[]>(() =>
    storyline().map((c) => ({ ...c, current: c.id === "manual" })),
  );
  return (
    <Checkpoints
      className="w-full max-w-lg"
      checkpoints={checkpoints}
      onRestore={(id) => setCheckpoints((l) => l.map((c) => ({ ...c, current: c.id === id })))}
    />
  );
}
```

### Empty (state)

```tsx
import { Checkpoints } from "@kura-ui/react/checkpoints";

export function CheckpointsEmpty() {
  return <Checkpoints className="w-full max-w-md" checkpoints={[]} />;
}
```

### With run-header (composition)

Restoring rewinds the run's step count and pauses it; Resume returns to the latest checkpoint.

```tsx
"use client";

import * as React from "react";
import { RunHeader } from "@kura-ui/react/run-header";
import { type Checkpoint, Checkpoints } from "@kura-ui/react/checkpoints";

const sec = (s: number) => Date.now() - s * 1000;

function storyline(): Checkpoint[] {
  return [
    {
      id: "tests",
      label: "Updated login and session tests",
      at: sec(150),
      filesChanged: 3,
      kind: "auto",
      current: true,
    },
    { id: "mw", label: "Patched src/middleware.ts", at: sec(290), filesChanged: 1, kind: "auto" },
    { id: "manual", label: "Before middleware changes", at: sec(370), kind: "manual" },
    {
      id: "client",
      label: "Replaced fetchUser() with auth.getSession()",
      at: sec(430),
      filesChanged: 9,
      kind: "auto",
    },
    { id: "start", label: "Run started on kura/auth-client", at: sec(720), kind: "auto" },
  ];
}

const STEP_OF: Record<string, number> = { tests: 5, mw: 4, manual: 3, client: 3, start: 0 };

export function CheckpointsComposition() {
  const [startedAt] = React.useState(() => sec(744));
  const [checkpoints, setCheckpoints] = React.useState<Checkpoint[]>(storyline);
  const current = checkpoints.find((c) => c.current)?.id ?? "tests";
  const rewound = current !== "tests";
  return (
    <div className="flex w-full max-w-xl flex-col gap-2">
      <RunHeader
        variant="bar"
        title="Migrate session API to @acme/auth"
        status={rewound ? "paused" : "running"}
        startedAt={startedAt}
        progress={{ done: STEP_OF[current] ?? 0, total: 7 }}
        cost={1.46}
        budget={5}
        onPause={() => {}}
        onResume={() => setCheckpoints((l) => l.map((c) => ({ ...c, current: c.id === "tests" })))}
        onStop={() => {}}
        shortcuts={false}
      />
      <Checkpoints
        checkpoints={checkpoints}
        onRestore={(id) => setCheckpoints((l) => l.map((c) => ({ ...c, current: c.id === id })))}
      />
    </div>
  );
}
```

## Dependencies

- npm: `lucide-react`
- Kura registry items: `kura-theme`, `button`, `utils`
- Related: `run-header`, `diff-view`, `file-changes`, `task-list`

---

# 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: "AbortController – Web APIs",
    url: "https://developer.mozilla.org/en-US/docs/Web/API/AbortController",
    siteName: "MDN",
    snippet:
      "The AbortController interface represents a controller object that allows you to abort one or more Web requests as and when desired.",
  },
];

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: "AbortController – Web APIs",
    url: "https://developer.mozilla.org/en-US/docs/Web/API/AbortController",
    siteName: "MDN",
    snippet:
      "The AbortController interface represents a controller object that allows you to abort one or more Web requests as and when desired.",
  },
];

export function CitationFull() {
  return (
    <div className="flex w-full max-w-xl flex-col gap-4">
      <p className="text-[15px] text-kura-fg leading-relaxed">
        Render the new count immediately with{" "}
        <code className="rounded-kura-xs bg-kura-active px-[0.3em] py-[0.1em] font-kura-mono text-[0.86em]">
          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 abort the stale request if
        the reader taps again
        <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: "AbortController – Web APIs",
    url: "https://developer.mozilla.org/en-US/docs/Web/API/AbortController",
    siteName: "MDN",
    snippet:
      "The AbortController interface represents a controller object that allows you to abort one or more Web requests as and when desired.",
  },
];

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: "AbortController – Web APIs",
    url: "https://developer.mozilla.org/en-US/docs/Web/API/AbortController",
    siteName: "MDN",
    snippet:
      "The AbortController interface represents a controller object that allows you to abort one or more Web requests as and when desired.",
  },
];

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).
- The default palette is deliberately quiet: grey value carries structure (keywords/attributes fg-muted, punctuation/comments fg-subtle) and only strings, numbers and types get a low-chroma tint. Theme it with CSS variables on any ancestor: --kura-syntax-keyword, -string, -constant, -function, -type, -tag, -attr, -property, -comment, -punctuation.
- `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.

```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);
  return (
    <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
      header
      className="w-full max-w-xl"
    />
  );
}
```

### 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 (opaque raised surface over a dimming scrim, 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 type { AttachmentItem } from "@kura-ui/react/attachment";
import { KbdShortcut } from "@kura-ui/react/kbd-shortcut";
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 aria-pressed:shadow-[inset_0_0_0_1px_var(--kura-border-subtle)] [&_svg]:size-3.5"
    >
      {icon}
      {children}
    </button>
  );
}

const boardFiles: AttachmentItem[] = [
  { id: "deck", name: "q3-board-deck.pdf", type: "application/pdf", size: 4_820_000 },
  { id: "cohorts", name: "churn-by-cohort.csv", type: "text/csv", size: 312_000 },
];

export function ComposerFull() {
  const [value, setValue] = React.useState(
    "Check the churn figures on slide 7 against the cohort CSV and flag anything that doesn’t reconcile.",
  );
  const [status, setStatus] = React.useState<ComposerStatus>("idle");
  const [model, setModel] = React.useState("sonnet");
  const [search, setSearch] = React.useState(false);
  const [think, setThink] = React.useState(true);
  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-2.5">
      <Composer
        value={value}
        onValueChange={setValue}
        defaultAttachments={boardFiles}
        status={status}
        maxLength={4000}
        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="Ask about these files, or drop more…"
          minRows={2}
          maxRows={10}
        />
        <ComposerToolbar>
          <ComposerTools>
            <ComposerAttachButton />
            <ModelPicker models={models} value={model} onValueChange={setModel} side="top" />
            <span aria-hidden className="mx-0.5 h-4 w-px bg-kura-border" />
            <ToolToggle pressed={think} onPressedChange={setThink} icon={<Lightbulb />}>
              Think
            </ToolToggle>
            <ToolToggle pressed={search} onPressedChange={setSearch} icon={<Globe />}>
              Search
            </ToolToggle>
          </ComposerTools>
          <ComposerActions>
            <ComposerHint showAt={0.8} />
            <ComposerSubmit />
          </ComposerActions>
        </ComposerToolbar>
      </Composer>
      <div className="flex min-h-5 items-center justify-between gap-3 px-1.5">
        <p className="truncate text-kura-fg-subtle text-xs" aria-live="polite">
          {status === "submitted"
            ? "Sending…"
            : status === "streaming"
              ? "Responding · Esc to stop"
              : last
                ? `Sent with ${last.attachments.length} ${last.attachments.length === 1 ? "file" : "files"}`
                : "Kura reads attachments in full; tables over 50k rows are sampled."}
        </p>
        <div className="hidden shrink-0 items-center gap-3 sm:flex">
          <KbdShortcut keys={["enter"]} label="Send" variant="ghost" />
          <KbdShortcut keys={["shift", "enter"]} label="New line" variant="ghost" />
        </div>
      </div>
    </div>
  );
}
```

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

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

function StateLabel({ children }: { children: React.ReactNode }) {
  return <p className="px-1.5 pb-1.5 font-medium text-kura-fg-subtle text-xs">{children}</p>;
}

export function ComposerStates() {
  return (
    <div className="flex w-full max-w-xl flex-col gap-5">
      <div>
        <StateLabel>Submitted — waiting for the first token</StateLabel>
        <Composer
          defaultValue="Summarise the attached incident report for the #eng-oncall channel."
          status="submitted"
        >
          <ComposerInput />
          <ComposerToolbar>
            <ComposerTools>
              <ComposerAttachButton />
            </ComposerTools>
            <ComposerActions>
              <ComposerSubmit />
            </ComposerActions>
          </ComposerToolbar>
        </Composer>
      </div>
      <div>
        <StateLabel>Streaming, close to the character limit</StateLabel>
        <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>
      </div>
      <div>
        <StateLabel>Disabled</StateLabel>
        <Composer
          disabled
          placeholder="You’ve reached this week’s Opus limit. Resets Monday at 09:00."
        />
      </div>
    </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-[-0.02em]">
          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} />;
}
```

### Thread header with a breakdown (full)

A ring in the thread header and a bar with a footer note, both with the segment breakdown on hover. Attach logs to watch the numbers roll into warning and danger.

```tsx
"use client";

import { Paperclip } 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 [logs, setLogs] = React.useState(0);
  const segments = BASE.map((s) =>
    s.id === "files" ? { ...s, tokens: s.tokens + logs * 24_000 } : s,
  );
  return (
    <div 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 py-3">
        <div className="flex min-w-0 flex-col gap-0.5">
          <span className="truncate font-medium text-kura-fg text-sm tracking-[-0.01em]">
            Auth middleware refactor
          </span>
          <span className="text-kura-fg-subtle text-xs">32 turns · 200k context window</span>
        </div>
        <ContextMeter
          max={200_000}
          segments={segments}
          variant="ring"
          valueDisplay="percent"
          warningAt={0.7}
          dangerAt={0.9}
          label="Context"
        />
      </div>
      <div className="flex items-center justify-between gap-3 px-4 py-3 shadow-[inset_0_1px_0_var(--kura-border-subtle)]">
        <ContextMeter
          max={200_000}
          segments={segments}
          variant="bar"
          valueDisplay="tokens"
          className="-ml-1.5"
          footer="Files count once per turn; tool definitions are cached."
        />
        <div className="flex items-center gap-1">
          {logs > 0 && (
            <Button variant="ghost" size="xs" onClick={() => setLogs(0)}>
              Clear
            </Button>
          )}
          <Button variant="secondary" size="xs" onClick={() => setLogs((n) => n + 1)}>
            <Paperclip /> Attach server.log
          </Button>
        </div>
      </div>
    </div>
  );
}
```

### Thresholds (state)

ok, warning and danger bars in a list of threads, each labelled by its thread.

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

const THREADS = [
  { title: "Onboarding emails", used: 52_000 },
  { title: "Q3 data migration", used: 98_500 },
  { title: "Incident review: checkout", used: 121_900 },
];

export function ContextMeterThresholds() {
  return (
    <ul className="flex w-full max-w-md flex-col">
      {THREADS.map((t) => (
        <li
          key={t.title}
          className="flex h-10 items-center justify-between gap-4 text-[13px] text-kura-fg shadow-[inset_0_-1px_0_var(--kura-border-subtle)] last:shadow-none"
        >
          <span className="min-w-0 truncate">{t.title}</span>
          <ContextMeter max={128_000} used={t.used} variant="bar" label={t.title} />
        </li>
      ))}
    </ul>
  );
}
```

### In a composer footer (composition)

Next to the attach and send IconButtons of a composer.

```tsx
import { ArrowUp, Paperclip } 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">
        <div className="flex items-center gap-1">
          <IconButton label="Attach files" size="sm" icon={<Paperclip />} />
          <ContextMeter max={200_000} segments={BASE} />
        </div>
        <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`

---

# Diff View

> Code review for agent edits: a parsed unified diff with syntax and word highlights, line numbers, and per-hunk Accept / Reject with j/k/a/r keys.

- **Slug:** `diff-view` · **Category:** workspace · **Status:** experimental
- **Import:** `import { DiffFile, DiffFileInput, DiffFileStatus, DiffHunk, DiffHunkInput, DiffLine, DiffLineKind, DiffReview, DiffReviewChange, DiffView, HunkDecision } from "@kura-ui/react/diff-view";`
- **Docs:** https://kuro.abstergo.fyi/components/diff-view
- **Registry item:** https://kuro.abstergo.fyi/r/diff-view.json
- **Tags:** diff, code-review, patch, git, accept-reject, agent, syntax-highlighting, workspace

## Install

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

## When to use

- Let a user review the edits a coding agent made (Claude Code, Codex, Cursor-style) before applying or committing them.
- Show `git diff` / `git show` output or a model-written patch as a readable, highlighted diff.
- Per-change approval: accept or reject individual hunks, a whole file, or everything, and act on the resulting decisions.
- A read-only diff of what changed in a run (reviewable={false}).

## When not to use

- Listing which files changed without showing contents — use file-changes (it composes well beside DiffView).
- Showing a single code snippet or a whole file — use code-block.
- Command or test output — use terminal.
- Approving a tool call or command before it runs — use approval-prompt.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `diff` | `string` | — | no | A unified diff (`git diff`, `git show`, `diff -u`, a model's patch). Parsed with parseUnifiedDiff: renames, new/deleted/binary files, quoted paths, CRLF, missing counts, `\ No newline at end of file`, and wrong hunk counts are handled. Ignored when `files` is given. |
| `files` | `readonly DiffFileInput[]` | — | no | Structured files `{ path, oldPath?, status?, language?, binary?, hunks: [{ id?, oldStart?, newStart?, section?, lines }] }`. `lines` may be DiffLine objects or raw strings ("+added", "-removed", " context"); line numbers are computed. |
| `title` | `React.ReactNode` | `"Changes"` | no | Header title. |
| `reviewable` | `boolean` | `true` | no | Show per-hunk Accept / Reject, per-file Accept file, Accept all / Reject all and the “2 of 5 reviewed” tally. |
| `review` | `DiffReview` | — | no | Decisions (controlled): `{ [hunkId]: "accepted" \| "rejected" }`; absent = pending. Hunk ids are `hunk.id` or `<path>#<index>` (see hunkId()). |
| `defaultReview` | `DiffReview` | `{}` | no | Initial decisions when uncontrolled. |
| `onReviewChange` | `(review: DiffReview, change: DiffReviewChange) => void` | — | no | Called with the full next review state and `{ path, hunkIds, decision }` where decision is "accepted", "rejected" or "pending" (undo). |
| `collapsed` | `readonly string[]` | — | no | Collapsed file paths (controlled). |
| `defaultCollapsed` | `readonly string[]` | `[]` | no | Initially collapsed file paths when uncontrolled. |
| `onCollapsedChange` | `(collapsed: string[]) => void` | — | no | Called when a file is collapsed or expanded (by click or by collapseReviewed). |
| `collapseReviewed` | `boolean` | `true` | no | Collapse a file once every hunk in it has a decision (like GitHub's “Viewed”). |
| `autoAdvance` | `boolean` | `true` | no | After a decision, move focus to the next pending hunk (Cursor-style review flow). |
| `wrap` | `boolean` | `false` | no | Soft-wrap long lines instead of scrolling each hunk sideways. |
| `maxHeight` | `number` | — | no | Scroll the files inside this height (px). File headers stay pinned while scrolling (also against page scroll without it). |
| `actions` | `React.ReactNode` | — | no | Extra controls at the end of the header, e.g. a Commit button. |
| `empty` | `React.ReactNode` | — | no | Rendered when there are no files. Default an icon + “No changes”. |

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

## Anatomy

- **DiffView** (`data-slot="diff-view"`) — `data-state="empty" | "pending" | "reviewed"`, `data-reviewable`. A container query hides secondary header items below ~26–34rem.
- **Header** (`data-slot="diff-view-header"`) — Title, mono summary (`diff-view-summary`: files, +N −M), review progress (`diff-view-progress`) and Accept all / Reject all.
- **File** (`data-slot="diff-view-file"`) — `<section aria-label={path}>` with `data-status="added" | "modified" | "deleted" | "renamed"` and `data-state="open" | "closed"`.
- **FileHeader** (`data-slot="diff-view-file-header"`) — Sticky row: collapse toggle (button, aria-expanded), path (`diff-view-path`: dim directory + bold name, old → new for renames), status chip, +N −M, 5-block ratio bar (`diff-view-ratio`), Accept file / review state (`diff-view-file-review`).
- **Hunk** (`data-slot="diff-view-hunk"`) — `role="group"`, roving tabindex, `data-hunk-id`, `data-review="pending" | "accepted" | "rejected"`. Accent bar on the left when focused.
- **HunkHeader** (`data-slot="diff-view-hunk-header"`) — `@@ −a,b +c,d @@` + section heading, and Reject / Accept (`diff-view-hunk-actions`) or the decision (`diff-view-hunk-state`) with Undo.
- **Line** (`data-slot="diff-view-line"`) — `data-kind="context" | "add" | "remove"`: old and new line numbers, sign, highlighted code with word-level change marks.

## Accessibility

- Each file is a labelled section; its header toggle is a button with aria-expanded/aria-controls.
- Hunks are focusable groups named “Change 2 of 9, src/auth/client.ts lines 10–19, pending review”; only the current hunk (and its buttons) is in the Tab order.
- Added/removed lines carry sr-only “added:” / “removed:” prefixes; colour is never the only signal (+/− signs, status chips, labels).
- Decisions are announced in a polite status region (“Accepted hunk in src/middleware.ts. 3 of 9 reviewed.”) — once per action, never per render.
- Accept / Reject tooltips show their single-key shortcuts.
- Reduced motion: Chevron rotation, the review-dimming fade and the progress colour change apply instantly; no motion is essential.

| Keys | Action |
| --- | --- |
| J / K | Next / previous hunk (skips collapsed files) |
| A | Accept the focused hunk, then move to the next pending one |
| R | Reject the focused hunk, then move to the next pending one |
| U / Backspace | Undo the focused hunk's decision |
| Enter / Space | On a file header: collapse or expand the file |
| Tab | Through file headers and the focused hunk's buttons |

## Notes for agents

- Pass the raw `git diff` string to `diff`; don't pre-split it. Use `files` when you already have structured hunks (raw '+'/'-'/' ' strings are fine as lines).
- Review state is keyed by hunk id: `hunk.id` if you set one (do this when hunks can shift, e.g. while an agent keeps editing), else `<path>#<index>`. Export `hunkId(file, hunk, index)` to compute it.
- To apply decisions, walk parseUnifiedDiff(diff) and keep hunks whose id is "accepted"; rejected and pending hunks are not applied.
- Helpers exported alongside: parseUnifiedDiff, normalizeFiles, wordDiff, countChanges, languageFromPath.
- Syntax highlighting uses code-block's synchronous highlighter; the language is inferred from the file extension (override with files[].language).
- Very large diffs render every line; collapse big files with defaultCollapsed (e.g. lockfiles) to keep it fast.

## Examples

### Basic (minimal)

One file from a unified diff string, with per-hunk review.

```tsx
import { DiffView } from "@kura-ui/react/diff-view";

const MIDDLEWARE_DIFF = `diff --git a/src/middleware.ts b/src/middleware.ts
--- a/src/middleware.ts
+++ b/src/middleware.ts
@@ -1,4 +1,4 @@
 import { NextResponse, type NextRequest } from "next/server";
-import { readSessionCookie } from "@/lib/legacy-session";
+import { auth } from "@/auth/client";
 
 const PUBLIC_PATHS = ["/login", "/signup", "/api/health"];
@@ -8,5 +8,5 @@ export async function middleware(request: NextRequest) {
   if (PUBLIC_PATHS.some((p) => pathname.startsWith(p))) return NextResponse.next();
 
-  const session = readSessionCookie(request.headers.get("cookie"));
+  const session = await auth.getSession({ headers: request.headers });
   if (!session) {
     const url = new URL("/login", request.url);
`;

export function DiffViewMinimal() {
  return <DiffView diff={MIDDLEWARE_DIFF} className="w-full max-w-2xl" />;
}
```

### Review session (full)

The agent's whole migration (4 files, 9 hunks) with controlled review state, a scrolling body, pinned file headers and a keyboard legend. Try j, k, a, r, u.

```tsx
"use client";

import * as React from "react";
import { Kbd } from "@kura-ui/react/kbd";
import { type DiffReview, DiffView } from "@kura-ui/react/diff-view";

const AUTH_MIGRATION_DIFF = `diff --git a/src/auth/client.ts b/src/auth/client.ts
index 887cccf..1c08d5a 100644
--- a/src/auth/client.ts
+++ b/src/auth/client.ts
@@ -1,7 +1,8 @@
 import { cache } from "react";
-import { fetchJson } from "@/lib/http";
-import type { Session, User } from "./types";
+import { createAuthClient, type Session, type User } from "@acme/auth";
 
-const SESSION_URL = "/api/v1/session";
-const REFRESH_URL = "/api/v1/session/refresh";
+export const auth = createAuthClient({
+  baseUrl: process.env.NEXT_PUBLIC_AUTH_URL,
+  refresh: "auto",
+});
 
@@ -9,14 +10,10 @@ const REFRESH_URL = "/api/v1/session/refresh";
 export const fetchUser = cache(async (): Promise<User | null> => {
-  const res = await fetchJson<Session>(SESSION_URL, { credentials: "include" });
-  if (!res.ok) return null;
-  return res.data.user;
+  const session = await auth.getSession();
+  return session?.user ?? null;
 });
 
-export async function refreshSession(token: string): Promise<Session> {
-  const res = await fetchJson<Session>(REFRESH_URL, {
-    method: "POST",
-    body: JSON.stringify({ token }),
-  });
-  if (!res.ok) throw new Error(\`refresh failed: \${res.status}\`);
-  return res.data;
+export async function refreshSession(session: Session): Promise<Session> {
+  const next = await auth.refresh(session.refreshToken);
+  if (!next) throw new Error("refresh failed: session revoked");
+  return next;
 }
@@ -24,3 +21,3 @@ export async function refreshSession(token: string): Promise<Session> {
 export function isExpired(session: Session, now = Date.now()): boolean {
-  return session.expiresAt < now;
+  return session.expiresAt <= now;
 }
@@ -28,3 +25,3 @@ export function isExpired(session: Session, now = Date.now()): boolean {
 export async function signOut(): Promise<void> {
-  await fetchJson(SESSION_URL, { method: "DELETE", credentials: "include" });
+  await auth.signOut();
 }
diff --git a/src/auth/__tests__/login.test.ts b/src/auth/__tests__/login.test.ts
index 9fe0aaf..711a4bd 100644
--- a/src/auth/__tests__/login.test.ts
+++ b/src/auth/__tests__/login.test.ts
@@ -1,4 +1,4 @@
 import { describe, expect, it, vi } from "vitest";
-import { refreshSession, isExpired } from "../client";
+import { auth, isExpired, refreshSession } from "../client";
 
 describe("login", () => {
@@ -8,8 +8,10 @@ describe("login", () => {
 
   it("refreshes an expired session", async () => {
-    vi.spyOn(globalThis, "fetch").mockResolvedValue(
-      new Response(JSON.stringify({ expiresAt: 10, user: { id: "u_1" } })),
-    );
-    const next = await refreshSession("tok_expired");
+    vi.spyOn(auth, "refresh").mockResolvedValue({
+      expiresAt: 10,
+      refreshToken: "tok_next",
+      user: { id: "u_1" },
+    } as never);
+    const next = await refreshSession({ refreshToken: "tok_expired" } as never);
     expect(next.user.id).toBe("u_1");
   });
diff --git a/src/lib/legacy-session.ts b/src/lib/legacy-session.ts
deleted file mode 100644
index f0ae86d..0000000
--- a/src/lib/legacy-session.ts
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @deprecated Use \`auth.getSession()\` from @acme/auth. */
-export function readSessionCookie(cookie: string | null) {
-  const raw = cookie?.match(/acme_session=([^;]+)/)?.[1];
-  if (!raw) return null;
-  try {
-    return JSON.parse(atob(raw)) as { userId: string; expiresAt: number };
-  } catch {
-    return null;
-  }
-}
diff --git a/src/middleware.ts b/src/middleware.ts
index 0e93409..7eda2e2 100644
--- a/src/middleware.ts
+++ b/src/middleware.ts
@@ -1,4 +1,4 @@
 import { NextResponse, type NextRequest } from "next/server";
-import { readSessionCookie } from "@/lib/legacy-session";
+import { auth } from "@/auth/client";
 
 const PUBLIC_PATHS = ["/login", "/signup", "/api/health"];
@@ -8,5 +8,5 @@ export async function middleware(request: NextRequest) {
   if (PUBLIC_PATHS.some((p) => pathname.startsWith(p))) return NextResponse.next();
 
-  const session = readSessionCookie(request.headers.get("cookie"));
+  const session = await auth.getSession({ headers: request.headers });
   if (!session) {
     const url = new URL("/login", request.url);
`;

export function DiffViewFull() {
  const [review, setReview] = React.useState<DiffReview>({
    "src/auth/client.ts#0": "accepted",
  });
  const decisions = Object.values(review);
  const accepted = decisions.filter((d) => d === "accepted").length;
  const rejected = decisions.length - accepted;
  return (
    <div className="flex w-full max-w-3xl flex-col gap-3">
      <DiffView
        title="Review changes"
        diff={AUTH_MIGRATION_DIFF}
        review={review}
        onReviewChange={setReview}
        maxHeight={620}
      />
      <div className="flex items-center gap-3 px-1 text-[12px] text-kura-fg-subtle">
        <span className="flex items-center gap-1.5">
          <Kbd size="sm">J</Kbd>
          <Kbd size="sm">K</Kbd>
          <span>move</span>
        </span>
        <span className="flex items-center gap-1.5">
          <Kbd size="sm">A</Kbd>
          <span>accept</span>
        </span>
        <span className="flex items-center gap-1.5">
          <Kbd size="sm">R</Kbd>
          <span>reject</span>
        </span>
        <span className="flex items-center gap-1.5">
          <Kbd size="sm">U</Kbd>
          <span>undo</span>
        </span>
        <span className="ml-auto font-kura-mono tabular-nums">
          {accepted} accepted · {rejected} rejected
        </span>
      </div>
    </div>
  );
}
```

### Structured files (variant)

Rename, new file and a binary file from structured input; read-only.

```tsx
import { type DiffFileInput, DiffView } from "@kura-ui/react/diff-view";

const STRUCTURED_FILES: DiffFileInput[] = [
  {
    path: "src/auth/session-store.ts",
    oldPath: "src/auth/session.ts",
    status: "renamed",
    hunks: [
      {
        oldStart: 3,
        newStart: 3,
        section: "export class SessionStore",
        lines: [
          "   #ttl = 15 * 60_000;",
          "-  read(key: string) {",
          "+  read(key: string): Session | undefined {",
          "     return this.#map.get(key);",
        ],
      },
    ],
  },
  {
    path: "src/auth/types.ts",
    status: "added",
    hunks: [
      {
        newStart: 1,
        lines: [
          '+export type { Session, User } from "@acme/auth";',
          "+",
          '+export type AuthProvider = "password" | "github" | "google";',
        ],
      },
    ],
  },
  { path: "public/og-login.png", status: "modified", binary: true, hunks: [] },
];

export function DiffViewStructured() {
  return (
    <DiffView
      title="Patch from test-writer"
      files={STRUCTURED_FILES}
      reviewable={false}
      className="w-full max-w-2xl"
    />
  );
}
```

### Apply accepted changes (composition)

A footer bar with a Button acts on the accepted hunks.

```tsx
"use client";

import * as React from "react";
import { Button } from "@kura-ui/react/button";
import { type DiffReview, DiffView } from "@kura-ui/react/diff-view";

const MIDDLEWARE_DIFF = `diff --git a/src/middleware.ts b/src/middleware.ts
--- a/src/middleware.ts
+++ b/src/middleware.ts
@@ -1,4 +1,4 @@
 import { NextResponse, type NextRequest } from "next/server";
-import { readSessionCookie } from "@/lib/legacy-session";
+import { auth } from "@/auth/client";
 
 const PUBLIC_PATHS = ["/login", "/signup", "/api/health"];
@@ -8,5 +8,5 @@ export async function middleware(request: NextRequest) {
   if (PUBLIC_PATHS.some((p) => pathname.startsWith(p))) return NextResponse.next();
 
-  const session = readSessionCookie(request.headers.get("cookie"));
+  const session = await auth.getSession({ headers: request.headers });
   if (!session) {
     const url = new URL("/login", request.url);
`;

export function DiffViewComposition() {
  const [review, setReview] = React.useState<DiffReview>({});
  const [applied, setApplied] = React.useState<number | null>(null);
  const accepted = Object.values(review).filter((d) => d === "accepted").length;
  return (
    <div className="flex w-full max-w-3xl flex-col gap-3">
      <DiffView
        title="kura/auth-client"
        diff={MIDDLEWARE_DIFF}
        review={review}
        onReviewChange={(next) => {
          setReview(next);
          setApplied(null);
        }}
      />
      <div className="flex items-center justify-between gap-3 rounded-kura-xl bg-kura-surface py-2 pr-2 pl-3.5 shadow-kura-sm">
        <span className="text-[13px] text-kura-fg-muted" role="status">
          {applied != null
            ? `Applied ${applied} ${applied === 1 ? "change" : "changes"} to kura/auth-client`
            : accepted > 0
              ? `${accepted} accepted ${accepted === 1 ? "change" : "changes"} ready`
              : "Accept changes to apply them"}
        </span>
        <Button size="sm" disabled={accepted === 0} onClick={() => setApplied(accepted)}>
          Apply changes
        </Button>
      </div>
    </div>
  );
}
```

## Dependencies

- npm: `lucide-react`
- Kura registry items: `kura-theme`, `button`, `code-block`, `icon-button`, `tooltip`, `use-controllable-state`, `utils`
- Related: `file-changes`, `code-block`, `terminal`, `approval-prompt`, `tool-call`

---

# File Changes

> The files an agent touched: a compact folder tree or flat list with A/M/D/R status, +/− counts, live “editing” markers and selection.

- **Slug:** `file-changes` · **Category:** workspace · **Status:** experimental
- **Import:** `import { FileChange, FileChangeStatus, FileChanges } from "@kura-ui/react/file-changes";`
- **Docs:** https://kuro.abstergo.fyi/components/file-changes
- **Registry item:** https://kuro.abstergo.fyi/r/file-changes.json
- **Tags:** files, changes, git, tree, agent, status, sidebar, workspace

## Install

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

## When to use

- Show which files a coding agent has changed during or after a run (a sidebar next to the conversation or a diff).
- Indicate live activity: which file the agent is reading or editing right now.
- A file picker for a review screen: select a file to show its diff in diff-view.

## When not to use

- Showing the actual line changes — use diff-view (pair them: FileChanges as navigation, DiffView as content).
- A step-by-step log of the agent's actions — use agent-timeline or task-list.
- A general file browser or editor tree with create/rename/drag — this is a read-only change list.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `files` | `readonly FileChange[]` | — | yes | `{ path, status: "A" \| "M" \| "D" \| "R", oldPath?, additions?, deletions?, state?: "reading" \| "editing" }`. Paths are repo-relative with "/" separators. |
| `title` | `React.ReactNode` | `"Changes"` | no | Header title. |
| `view` | `"tree" \| "list"` | — | no | tree = folders (single-child chains compacted like VS Code, folders first); list = flat, file name then dimmed directory. Controlled. |
| `defaultView` | `"tree" \| "list"` | `"tree"` | no | Initial view when uncontrolled. |
| `onViewChange` | `(view: "tree" \| "list") => void` | — | no | Called when the header toggle switches views. |
| `viewToggle` | `boolean` | `true` | no | Show the tree/list toggle in the header. |
| `selectedPath` | `string \| null` | — | no | The selected file path (controlled). Pass null for no selection. |
| `defaultSelectedPath` | `string \| null` | `null` | no | Initially selected file when uncontrolled. |
| `onSelect` | `(path: string) => void` | — | no | Called when a file is chosen by click, Enter or Space. |
| `defaultCollapsed` | `readonly string[]` | — | no | Folder paths collapsed initially, e.g. ["src/auth/__tests__"]. |
| `maxHeight` | `number` | — | no | Scroll the rows inside this height (px). |
| `actions` | `React.ReactNode` | — | no | Extra header controls. |
| `empty` | `React.ReactNode` | — | no | Rendered when `files` is empty. Default an icon + “No changes yet”. |

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

## Anatomy

- **FileChanges** (`data-slot="file-changes"`) — `data-view="tree" | "list"`.
- **Header** (`data-slot="file-changes-header"`) — Title, summary (`file-changes-summary`: “7 files +33 −38”), actions, view toggle.
- **Rows** (`data-slot="file-changes-rows"`) — role="tree" (tree view) or role="listbox" (list view).
- **Folder** (`data-slot="file-changes-folder"`) — treeitem with aria-expanded, `data-state="open" | "closed"`; collapsed folders show their file count and a pulsing dot if a file inside is being edited.
- **File** (`data-slot="file-changes-file"`) — treeitem/option with aria-selected, `data-status="A" | "M" | "D" | "R"`, `data-state="reading" | "editing"`, `data-selected`. Selected rows get bg-kura-active and a 2px accent bar.
- **Name** (`data-slot="file-changes-name"`) — Mono file name; shimmers while editing, struck through when deleted.
- **Counts** (`data-slot="file-changes-counts"`) — +N −M in mono, or “editing” (accent, pulsing dot) / “reading”.
- **Status** (`data-slot="file-changes-status"`) — Status letter: A green, M amber, D red, R muted; sr-only word (“, modified”).
- **Guide** (`data-slot="file-changes-guide"`) — Hairline indent guides in the tree.

## Accessibility

- Role: `tree | listbox`
- Tree view is a WAI-ARIA tree (treeitems with aria-level/posinset/setsize, aria-expanded on folders, aria-selected on files); list view is a listbox of options.
- One roving tab stop: Tab enters the list at the selected (or first) row.
- Each file's accessible name includes its status word and live state (“client.ts … , modified, being edited”).
- The view toggle buttons use aria-pressed and have tooltips.
- Reduced motion: The editing pulse and name shimmer stop; row fade-in and chevron rotation are instant.

| Keys | Action |
| --- | --- |
| ArrowDown / ArrowUp | Next / previous row |
| ArrowRight | Expand a folder, or move into it |
| ArrowLeft | Collapse a folder, or move to the parent folder |
| Home / End | First / last row |
| Enter / Space | Select a file, or toggle a folder |

## Notes for agents

- Map git porcelain codes directly: A/M/D/R (treat C copies as A, T type changes as M).
- Set `state: "editing"` on the file the agent is writing and clear it when done — the row shimmers and collapsed ancestor folders show a live dot.
- Selection is single and files-only; folders toggle. Use onSelect to drive a DiffView or editor beside it.
- Counts are optional; omit additions/deletions when unknown rather than passing 0.

## Examples

### Changed files (minimal)

Seven files from the auth migration as a folder tree.

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

const CHANGES: FileChange[] = [
  { path: "src/auth/client.ts", status: "M", additions: 13, deletions: 16 },
  { path: "src/auth/types.ts", status: "A", additions: 6 },
  { path: "src/auth/__tests__/login.test.ts", status: "M", additions: 7, deletions: 5 },
  { path: "src/middleware.ts", status: "M", additions: 2, deletions: 2 },
  { path: "src/lib/legacy-session.ts", status: "D", deletions: 10 },
  { path: "src/routes/account/page.tsx", status: "M", additions: 4, deletions: 4 },
  { path: "package.json", status: "M", additions: 1, deletions: 1 },
];

export function FileChangesMinimal() {
  return <FileChanges files={CHANGES} className="w-full max-w-sm" />;
}
```

### Live run (full)

Files appear as the agent reads and edits them — the active one shimmers with an “editing” marker — then the run settles. Controlled selection.

```tsx
"use client";

import * as React from "react";
import { type FileChange, FileChanges } from "@kura-ui/react/file-changes";

const STEPS: FileChange[][] = [
  [{ path: "src/auth/client.ts", status: "M", state: "reading" }],
  [{ path: "src/auth/client.ts", status: "M", additions: 4, deletions: 6, state: "editing" }],
  [
    { path: "src/auth/client.ts", status: "M", additions: 13, deletions: 16 },
    { path: "src/middleware.ts", status: "M", additions: 1, deletions: 1, state: "editing" },
  ],
  [
    { path: "src/auth/client.ts", status: "M", additions: 13, deletions: 16 },
    { path: "src/middleware.ts", status: "M", additions: 2, deletions: 2 },
    { path: "src/auth/types.ts", status: "A", additions: 3, state: "editing" },
  ],
  [
    { path: "src/auth/client.ts", status: "M", additions: 13, deletions: 16 },
    { path: "src/middleware.ts", status: "M", additions: 2, deletions: 2 },
    { path: "src/auth/types.ts", status: "A", additions: 6 },
    {
      path: "src/auth/__tests__/login.test.ts",
      status: "M",
      additions: 2,
      deletions: 3,
      state: "editing",
    },
  ],
  [
    { path: "src/auth/client.ts", status: "M", additions: 13, deletions: 16 },
    { path: "src/middleware.ts", status: "M", additions: 2, deletions: 2 },
    { path: "src/auth/types.ts", status: "A", additions: 6 },
    { path: "src/auth/__tests__/login.test.ts", status: "M", additions: 7, deletions: 5 },
    { path: "src/lib/legacy-session.ts", status: "D", deletions: 10 },
    {
      path: "src/routes/account/page.tsx",
      status: "M",
      additions: 1,
      deletions: 1,
      state: "editing",
    },
  ],
  CHANGES,
];

const CHANGES: FileChange[] = [
  { path: "src/auth/client.ts", status: "M", additions: 13, deletions: 16 },
  { path: "src/auth/types.ts", status: "A", additions: 6 },
  { path: "src/auth/__tests__/login.test.ts", status: "M", additions: 7, deletions: 5 },
  { path: "src/middleware.ts", status: "M", additions: 2, deletions: 2 },
  { path: "src/lib/legacy-session.ts", status: "D", deletions: 10 },
  { path: "src/routes/account/page.tsx", status: "M", additions: 4, deletions: 4 },
  { path: "package.json", status: "M", additions: 1, deletions: 1 },
];

export function FileChangesFull() {
  const [step, setStep] = React.useState(0);
  const [selected, setSelected] = React.useState<string | null>("src/auth/client.ts");
  React.useEffect(() => {
    if (step >= STEPS.length - 1) return;
    const id = setTimeout(() => setStep((s) => s + 1), step === 0 ? 1400 : 1800);
    return () => clearTimeout(id);
  }, [step]);
  return (
    <FileChanges
      title="Changes"
      files={STEPS[step]!}
      selectedPath={selected}
      onSelect={setSelected}
      className="w-full max-w-sm"
    />
  );
}
```

### Flat list (variant)

List view: file name first, directory dimmed.

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

const CHANGES: FileChange[] = [
  { path: "src/auth/client.ts", status: "M", additions: 13, deletions: 16 },
  { path: "src/auth/types.ts", status: "A", additions: 6 },
  { path: "src/auth/__tests__/login.test.ts", status: "M", additions: 7, deletions: 5 },
  { path: "src/middleware.ts", status: "M", additions: 2, deletions: 2 },
  { path: "src/lib/legacy-session.ts", status: "D", deletions: 10 },
  { path: "src/routes/account/page.tsx", status: "M", additions: 4, deletions: 4 },
  { path: "package.json", status: "M", additions: 1, deletions: 1 },
];

export function FileChangesList() {
  return (
    <FileChanges
      files={CHANGES}
      defaultView="list"
      defaultSelectedPath="src/middleware.ts"
      className="w-full max-w-md"
    />
  );
}
```

### With DiffView (composition)

FileChanges as navigation; DiffView shows the selected file parsed from the same unified diff.

```tsx
"use client";

import * as React from "react";
import { DiffView, parseUnifiedDiff } from "@kura-ui/react/diff-view";
import { type FileChange, FileChanges } from "@kura-ui/react/file-changes";

const REVIEW_FILES = parseUnifiedDiff(AUTH_MIGRATION_DIFF);

const AUTH_MIGRATION_DIFF = `diff --git a/src/auth/client.ts b/src/auth/client.ts
index 887cccf..1c08d5a 100644
--- a/src/auth/client.ts
+++ b/src/auth/client.ts
@@ -1,7 +1,8 @@
 import { cache } from "react";
-import { fetchJson } from "@/lib/http";
-import type { Session, User } from "./types";
+import { createAuthClient, type Session, type User } from "@acme/auth";
 
-const SESSION_URL = "/api/v1/session";
-const REFRESH_URL = "/api/v1/session/refresh";
+export const auth = createAuthClient({
+  baseUrl: process.env.NEXT_PUBLIC_AUTH_URL,
+  refresh: "auto",
+});
 
@@ -9,14 +10,10 @@ const REFRESH_URL = "/api/v1/session/refresh";
 export const fetchUser = cache(async (): Promise<User | null> => {
-  const res = await fetchJson<Session>(SESSION_URL, { credentials: "include" });
-  if (!res.ok) return null;
-  return res.data.user;
+  const session = await auth.getSession();
+  return session?.user ?? null;
 });
 
-export async function refreshSession(token: string): Promise<Session> {
-  const res = await fetchJson<Session>(REFRESH_URL, {
-    method: "POST",
-    body: JSON.stringify({ token }),
-  });
-  if (!res.ok) throw new Error(\`refresh failed: \${res.status}\`);
-  return res.data;
+export async function refreshSession(session: Session): Promise<Session> {
+  const next = await auth.refresh(session.refreshToken);
+  if (!next) throw new Error("refresh failed: session revoked");
+  return next;
 }
@@ -24,3 +21,3 @@ export async function refreshSession(token: string): Promise<Session> {
 export function isExpired(session: Session, now = Date.now()): boolean {
-  return session.expiresAt < now;
+  return session.expiresAt <= now;
 }
@@ -28,3 +25,3 @@ export function isExpired(session: Session, now = Date.now()): boolean {
 export async function signOut(): Promise<void> {
-  await fetchJson(SESSION_URL, { method: "DELETE", credentials: "include" });
+  await auth.signOut();
 }
diff --git a/src/auth/__tests__/login.test.ts b/src/auth/__tests__/login.test.ts
index 9fe0aaf..711a4bd 100644
--- a/src/auth/__tests__/login.test.ts
+++ b/src/auth/__tests__/login.test.ts
@@ -1,4 +1,4 @@
 import { describe, expect, it, vi } from "vitest";
-import { refreshSession, isExpired } from "../client";
+import { auth, isExpired, refreshSession } from "../client";
 
 describe("login", () => {
@@ -8,8 +8,10 @@ describe("login", () => {
 
   it("refreshes an expired session", async () => {
-    vi.spyOn(globalThis, "fetch").mockResolvedValue(
-      new Response(JSON.stringify({ expiresAt: 10, user: { id: "u_1" } })),
-    );
-    const next = await refreshSession("tok_expired");
+    vi.spyOn(auth, "refresh").mockResolvedValue({
+      expiresAt: 10,
+      refreshToken: "tok_next",
+      user: { id: "u_1" },
+    } as never);
+    const next = await refreshSession({ refreshToken: "tok_expired" } as never);
     expect(next.user.id).toBe("u_1");
   });
diff --git a/src/lib/legacy-session.ts b/src/lib/legacy-session.ts
deleted file mode 100644
index f0ae86d..0000000
--- a/src/lib/legacy-session.ts
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @deprecated Use \`auth.getSession()\` from @acme/auth. */
-export function readSessionCookie(cookie: string | null) {
-  const raw = cookie?.match(/acme_session=([^;]+)/)?.[1];
-  if (!raw) return null;
-  try {
-    return JSON.parse(atob(raw)) as { userId: string; expiresAt: number };
-  } catch {
-    return null;
-  }
-}
diff --git a/src/middleware.ts b/src/middleware.ts
index 0e93409..7eda2e2 100644
--- a/src/middleware.ts
+++ b/src/middleware.ts
@@ -1,4 +1,4 @@
 import { NextResponse, type NextRequest } from "next/server";
-import { readSessionCookie } from "@/lib/legacy-session";
+import { auth } from "@/auth/client";
 
 const PUBLIC_PATHS = ["/login", "/signup", "/api/health"];
@@ -8,5 +8,5 @@ export async function middleware(request: NextRequest) {
   if (PUBLIC_PATHS.some((p) => pathname.startsWith(p))) return NextResponse.next();
 
-  const session = readSessionCookie(request.headers.get("cookie"));
+  const session = await auth.getSession({ headers: request.headers });
   if (!session) {
     const url = new URL("/login", request.url);
`;

export function FileChangesComposition() {
  const [selected, setSelected] = React.useState("src/auth/client.ts");
  const files: FileChange[] = REVIEW_FILES.map((f) => {
    const lines = f.hunks.flatMap((h) => h.lines);
    return {
      path: f.path,
      status:
        f.status === "added"
          ? "A"
          : f.status === "deleted"
            ? "D"
            : f.status === "renamed"
              ? "R"
              : "M",
      additions: lines.filter((l) => l.kind === "add").length,
      deletions: lines.filter((l) => l.kind === "remove").length,
    };
  });
  const current = REVIEW_FILES.filter((f) => f.path === selected);
  return (
    <div className="grid w-full max-w-4xl items-start gap-3 md:grid-cols-[17rem_1fr]">
      <FileChanges
        files={files}
        selectedPath={selected}
        onSelect={setSelected}
        viewToggle={false}
      />
      <DiffView title={selected.split("/").pop()} files={current} reviewable={false} wrap />
    </div>
  );
}
```

## Dependencies

- npm: `lucide-react`
- Kura registry items: `kura-theme`, `icon-button`, `shimmer-text`, `use-controllable-state`, `utils`
- Related: `diff-view`, `terminal`, `agent-timeline`, `task-list`, `run-header`

---

# 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, Copy, Download, Mic, Paperclip, Pin, Plus, RotateCcw, Share, Trash2 } from "lucide-react";
import { IconButton } from "@kura-ui/react/icon-button";

export function IconButtonFull() {
  return (
    <div className="flex flex-col items-center gap-4">
      <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 aria-hidden 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"
        />
      </div>
      <div className="flex items-center gap-2">
        <IconButton label="Copy" icon={<Copy />} />
        <IconButton label="Download" icon={<Download />} variant="secondary" />
        <IconButton label="Share" icon={<Share />} variant="outline" />
        <IconButton
          label="New chat"
          icon={<Plus />}
          variant="primary"
          shortcut={["mod", "shift", "o"]}
        />
        <IconButton label="Delete" icon={<Trash2 />} variant="outline" disabled />
        <IconButton label="Pin" icon={<Pin />} size="xs" tooltip={false} />
      </div>
    </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 flex-wrap items-center justify-center gap-x-5 gap-y-2 text-[13px]">
        <span className="flex items-center gap-2">
          Run task <Kbd keys={["mod", "shift", "p"]} size="sm" />
        </span>
        <span className="flex items-center gap-2">
          Insert line <Kbd keys={["alt", "enter"]} variant="ghost" />
        </span>
        <span className="flex items-center gap-2">
          Edit last <Kbd keys={["up"]} pressed />
        </span>
      </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:** primitives · **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`

---

# 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 bubble (a translucent fg tint that separates from any surface, in both themes); 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"
        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`

---

# Popover

> Floating panel (opaque raised surface, hairline ring, soft shadow) 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 { Gauge } from "lucide-react";
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="outline">
          <Gauge /> Usage
        </Button>
      </PopoverTrigger>
      <PopoverContent aria-labelledby="usage-title" className="w-64">
        <div className="flex flex-col gap-2.5">
          <div className="flex items-baseline justify-between">
            <h3 id="usage-title" className="font-medium text-sm">
              Weekly usage
            </h3>
            <span className="text-kura-fg-muted text-xs tabular-nums">38 / 50</span>
          </div>
          <div className="h-1.5 overflow-hidden rounded-full bg-kura-gray-4">
            <div className="h-full w-[76%] rounded-full bg-kura-ink" />
          </div>
          <p className="text-kura-fg-muted text-xs leading-relaxed">
            Opus messages reset on Monday at 09:00. Haiku is unlimited.
          </p>
        </div>
      </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";

const efforts = ["Low", "Medium", "High"] as const;

export function PopoverFull() {
  const [open, setOpen] = React.useState(false);
  const [effort, setEffort] = React.useState<(typeof efforts)[number]>("Medium");
  const [temperature, setTemperature] = React.useState(0.7);
  return (
    <Popover open={open} onOpenChange={setOpen}>
      <PopoverTrigger asChild>
        <Button variant="outline">
          <Settings2 /> Generation settings
        </Button>
      </PopoverTrigger>
      <PopoverContent
        side="bottom"
        align="start"
        aria-labelledby="gen-settings-title"
        className="w-72 p-0"
      >
        <div className="flex flex-col gap-4 p-4">
          <div className="flex flex-col gap-0.5">
            <h3 id="gen-settings-title" className="font-medium text-sm">
              Generation
            </h3>
            <p className="text-kura-fg-muted text-xs">Applies to new replies in this chat.</p>
          </div>
          <fieldset className="flex flex-col">
            <legend className="mb-2 font-medium text-kura-fg-muted text-xs">
              Reasoning effort
            </legend>
            <div className="grid grid-cols-3 gap-0.5 rounded-kura-md bg-kura-surface-sunken p-0.5 shadow-[inset_0_0_0_1px_var(--kura-border-subtle)]">
              {efforts.map((option) => (
                <label
                  key={option}
                  className="flex h-7 cursor-pointer items-center justify-center rounded-kura-sm font-medium text-kura-fg-muted text-xs transition-[background-color,color,box-shadow] duration-(--kura-duration-fast) ease-kura-out hover:text-kura-fg has-checked:bg-kura-surface-raised has-checked:text-kura-fg has-checked:shadow-kura-sm has-focus-visible:shadow-kura-focus"
                >
                  <input
                    type="radio"
                    name="reasoning-effort"
                    value={option}
                    checked={effort === option}
                    onChange={() => setEffort(option)}
                    className="sr-only"
                  />
                  {option}
                </label>
              ))}
            </div>
          </fieldset>
          <label className="flex flex-col gap-2">
            <span className="flex items-center justify-between font-medium text-kura-fg-muted text-xs">
              Temperature
              <span className="font-kura-mono text-kura-fg tabular-nums">
                {temperature.toFixed(1)}
              </span>
            </span>
            <input
              type="range"
              min={0}
              max={1}
              step={0.1}
              value={temperature}
              onChange={(e) => setTemperature(Number(e.target.value))}
              className="h-4 w-full cursor-pointer accent-kura-ink"
            />
            <span className="flex justify-between text-[11px] text-kura-fg-subtle">
              <span>Precise</span>
              <span>Creative</span>
            </span>
          </label>
        </div>
        <div className="flex items-center justify-end gap-2 border-kura-border-subtle border-t px-4 py-3">
          <Button
            variant="ghost"
            size="sm"
            onClick={() => {
              setEffort("Medium");
              setTemperature(0.7);
            }}
          >
            Reset
          </Button>
          <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 Queue

> Stack of follow-up prompts queued while an agent works: reorder, edit inline, remove, or Send now to steer. Renders nothing when empty.

- **Slug:** `prompt-queue` · **Category:** agent · **Status:** experimental
- **Import:** `import { PromptQueue, QueuedPrompt, QueuedPromptAttachment } from "@kura-ui/react/prompt-queue";`
- **Docs:** https://kuro.abstergo.fyi/components/prompt-queue
- **Registry item:** https://kuro.abstergo.fyi/r/prompt-queue.json
- **Tags:** agent, queue, prompts, follow-up, steer, reorder, drag, composer

## Install

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

## When to use

- The user types follow-ups while an agent is mid-turn (Claude Code / Codex queued messages) and they should send in order when it finishes.
- Letting the user steer: interrupt the agent and send one queued prompt immediately.
- Directly above a composer (variant='tray') so queued prompts read as part of the input.

## When not to use

- Suggested prompts the user has not written — use prompt-suggestions.
- The prompt input itself — use composer (and put PromptQueue above it).
- Work the agent plans to do — use task-list.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `items` | `QueuedPrompt[]` | — | no | Queued prompts in send order (controlled): { id, text, attachments?: { name, type?: 'image' \| 'file' }[] }. |
| `defaultItems` | `QueuedPrompt[]` | — | no | Initial prompts when uncontrolled. |
| `onItemsChange` | `(items: QueuedPrompt[]) => void` | — | no | Called with the whole new list after a reorder, edit, remove or Send now. Fires on every step while dragging. |
| `onSendNow` | `(item: QueuedPrompt) => void` | — | no | Steer: interrupt the agent and send this prompt now. The prompt is removed from the queue first. Without it no Send now button renders. |
| `title` | `React.ReactNode` | `"Queued"` | no | Header title; the count follows it. |
| `hint` | `React.ReactNode` | `"Sends when the agent finishes this turn"` | no | Secondary header text, e.g. 'Sends when Kura finishes running pnpm test'. null hides it. |
| `variant` | `"panel" \| "tray"` | `"panel"` | no | panel = standalone card; tray = sunken, rounded on top only, meant to sit flush on top of a Composer (inset it with className='mx-3'). |

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

## Anatomy

- **PromptQueue** (`data-slot="prompt-queue"`) — Root with `data-variant`.
- **Header** (`data-slot="prompt-queue-header"`) — Title, count and prompt-queue-hint.
- **Item** (`data-slot="prompt-queue-item"`) — Focusable <li> (`data-state` = editing | dragging): index (grip on hover), text, attachments, actions.
- **Handle** (`data-slot="prompt-queue-handle"`) — Drag grip shown in place of the index on hover (pointer only; keyboard uses Alt+arrows or Space).
- **Text** (`data-slot="prompt-queue-text"`) — One truncated line; the full text is the title tooltip.
- **Attachments** (`data-slot="prompt-queue-attachments"`) — First attachment's icon and name in mono, then '+N'.
- **Actions** (`data-slot="prompt-queue-actions"`) — Move up, Move down, Edit, Remove and prompt-queue-send ('Send now'); shown on hover/focus, always on touch.
- **Editor** (`data-slot="prompt-queue-editor"`) — Auto-growing textarea replacing the row while editing, with Cancel/Save.

## Accessibility

- Role: `list (ol) of focusable items`
- The list is labelled by the title and described by visually hidden keyboard help. Items use a roving tabindex (one Tab stop) and are named '2 of 3: <text>'.
- A polite status region announces moves ('Moved to position 1 of 3'), removals and Send now. Actions are icon buttons with tooltips.
- Escape in the editor cancels without reaching the composer's own Escape (stop) handler.
- Reduced motion: Reorders jump into place instead of sliding; the drag still follows the pointer.

| Keys | Action |
| --- | --- |
| ArrowUp / ArrowDown | Move focus between prompts |
| Alt+ArrowUp / Alt+ArrowDown | Move the focused prompt up / down |
| Space, then arrows, then Space | Grab, move and drop (Escape restores) |
| Enter / F2 | Edit inline (Enter saves, Shift+Enter newline, Escape cancels) |
| Delete / Backspace | Remove |
| Mod+Enter | Send now |

## Notes for agents

- When the agent finishes a turn, shift the first item off `items` and send it yourself — the component never sends on its own.
- onSendNow means 'interrupt and send': stop the current turn in your harness before sending.
- Keep ids stable across edits; reordering and focus rely on them.
- Empty queue renders only a visually hidden status region, so you can leave it mounted above the composer.

## Examples

### Two queued prompts (minimal)

```tsx
"use client";

import { PromptQueue } from "@kura-ui/react/prompt-queue";

export function PromptQueueMinimal() {
  return (
    <PromptQueue
      className="w-full max-w-xl"
      defaultItems={[
        { id: "readme", text: "When tests pass, update the auth section of the README" },
        { id: "legacy", text: "Don't touch src/legacy/ — it's deleted next sprint" },
      ]}
      onSendNow={() => {}}
    />
  );
}
```

### Controlled, with steering (full)

Attachments, a prompt that arrives after mount, and Send now reported below.

```tsx
"use client";

import { CornerDownRight } from "lucide-react";
import * as React from "react";
import { PromptQueue, type QueuedPrompt } from "@kura-ui/react/prompt-queue";

const QUEUE: QueuedPrompt[] = [
  {
    id: "helper",
    text: "Use the refreshSession() helper instead of calling fetch('/api/session') directly",
    attachments: [{ name: "session-flow.png", type: "image" }],
  },
  {
    id: "legacy",
    text: "Don't touch src/legacy/ — it's being deleted next sprint",
  },
  {
    id: "readme",
    text: "When tests pass, update the auth section of the README and link the migration guide",
    attachments: [
      { name: "MIGRATION.md", type: "file" },
      { name: "auth-diagram.png", type: "image" },
    ],
  },
];

export function PromptQueueFull() {
  const [items, setItems] = React.useState<QueuedPrompt[]>(QUEUE);
  const [steered, setSteered] = React.useState<string | null>(null);

  // A teammate queues one more follow-up a moment after mount.
  React.useEffect(() => {
    const t = setTimeout(
      () =>
        setItems((list) =>
          list.some((i) => i.id === "pr")
            ? list
            : [...list, { id: "pr", text: "Open the PR as a draft and request review from @maya" }],
        ),
      1600,
    );
    return () => clearTimeout(t);
  }, []);

  return (
    <div className="flex w-full max-w-xl flex-col gap-2">
      <PromptQueue
        items={items}
        onItemsChange={setItems}
        onSendNow={(item) => setSteered(item.text)}
        hint="Sends when Kura finishes running pnpm test"
      />
      <p
        className="flex min-h-5 items-center gap-1.5 px-1 text-[12px] text-kura-fg-subtle"
        aria-live="polite"
      >
        {steered ? (
          <>
            <CornerDownRight aria-hidden className="size-3.5 shrink-0" strokeWidth={1.75} />
            <span className="truncate">
              Interrupted Kura and sent: <span className="text-kura-fg-muted">{steered}</span>
            </span>
          </>
        ) : (
          "Hover a prompt, or focus it and use Alt+↑/↓, Enter, Delete and ⌘↵."
        )}
      </p>
    </div>
  );
}
```

### Tray (variant)

Rounded on top only, tucked onto the input below.

```tsx
"use client";

import { PromptQueue, type QueuedPrompt } from "@kura-ui/react/prompt-queue";

const QUEUE: QueuedPrompt[] = [
  {
    id: "helper",
    text: "Use the refreshSession() helper instead of calling fetch('/api/session') directly",
    attachments: [{ name: "session-flow.png", type: "image" }],
  },
  {
    id: "legacy",
    text: "Don't touch src/legacy/ — it's being deleted next sprint",
  },
  {
    id: "readme",
    text: "When tests pass, update the auth section of the README and link the migration guide",
    attachments: [
      { name: "MIGRATION.md", type: "file" },
      { name: "auth-diagram.png", type: "image" },
    ],
  },
];

export function PromptQueueTray() {
  return (
    <div className="flex w-full max-w-xl flex-col">
      <PromptQueue
        variant="tray"
        className="mx-3"
        defaultItems={QUEUE.slice(0, 2)}
        onSendNow={() => {}}
      />
      <div className="h-16 rounded-kura-xl bg-kura-surface shadow-kura-sm" />
    </div>
  );
}
```

### Above a composer (composition)

Messages sent while the agent works are queued; Send now steers.

```tsx
"use client";

import { CornerDownRight } from "lucide-react";
import * as React from "react";
import { Composer } from "@kura-ui/react/composer";
import { RunHeader } from "@kura-ui/react/run-header";
import { PromptQueue, type QueuedPrompt } from "@kura-ui/react/prompt-queue";

const QUEUE: QueuedPrompt[] = [
  {
    id: "helper",
    text: "Use the refreshSession() helper instead of calling fetch('/api/session') directly",
    attachments: [{ name: "session-flow.png", type: "image" }],
  },
  {
    id: "legacy",
    text: "Don't touch src/legacy/ — it's being deleted next sprint",
  },
  {
    id: "readme",
    text: "When tests pass, update the auth section of the README and link the migration guide",
    attachments: [
      { name: "MIGRATION.md", type: "file" },
      { name: "auth-diagram.png", type: "image" },
    ],
  },
];

export function PromptQueueComposition() {
  const [items, setItems] = React.useState<QueuedPrompt[]>(QUEUE.slice(0, 2));
  const [log, setLog] = React.useState<string[]>([]);
  const [startedAt] = React.useState(() => Date.now() - 611_000);
  return (
    <div className="flex w-full max-w-xl flex-col gap-3">
      <RunHeader
        variant="bar"
        title="Run pnpm test --filter web"
        status="running"
        startedAt={startedAt}
        progress={{ done: 5, total: 7 }}
        cost={1.52}
        onStop={() => {}}
        shortcuts={false}
      />
      {log.length > 0 && (
        <ul className="flex flex-col gap-1 px-1 text-[12px] text-kura-fg-subtle">
          {log.map((l, i) => (
            <li key={i} className="flex items-center gap-1.5 truncate">
              <CornerDownRight aria-hidden className="size-3.5 shrink-0" strokeWidth={1.75} />
              Steered: <span className="truncate text-kura-fg-muted">{l}</span>
            </li>
          ))}
        </ul>
      )}
      <div className="flex flex-col">
        <PromptQueue
          variant="tray"
          className="mx-3"
          items={items}
          onItemsChange={setItems}
          onSendNow={(item) => setLog((l) => [...l, item.text])}
          hint="Sends after this turn"
        />
        <Composer
          className="relative"
          placeholder="Queue a follow-up for Kura…"
          onSubmit={(m) => setItems((list) => [...list, { id: `q-${Date.now()}`, text: m.text }])}
        />
      </div>
    </div>
  );
}
```

## Dependencies

- npm: `lucide-react`, `motion`
- Kura registry items: `kura-theme`, `button`, `icon-button`, `kura-motion`, `use-controllable-state`, `use-reduced-motion`, `utils`
- Related: `composer`, `run-header`, `prompt-suggestions`, `task-list`

---

# 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-3 text-[15px] text-kura-fg leading-relaxed">
      <Reasoning
        key={run}
        active={active}
        open={open}
        onOpenChange={setOpen}
        autoCollapse
        className="w-full"
      >
        <StreamingText stream={stream} caret={false} onComplete={() => setActive(false)} />
      </Reasoning>
      {!active && (
        <div className="flex animate-kura-fade-in flex-col items-start gap-3">
          <p>
            Wrap the click in a transition and render from{" "}
            <code className="rounded-kura-xs bg-kura-active px-[0.3em] py-[0.1em] font-kura-mono text-[0.86em]">
              useOptimistic
            </code>
            . The count updates on the same frame, and if the server action throws, React drops the
            optimistic value and the real count comes back on its own.
          </p>
          <Button variant="ghost" size="xs" className="-ml-2 text-kura-fg-muted" onClick={replay}>
            <RotateCcw /> Think again
          </Button>
        </div>
      )}
    </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`

---

# Run Header

> Header for one agent run: title, agent, model, branch, status, live elapsed clock, tokens, cost vs budget, step progress and Stop/Pause controls.

- **Slug:** `run-header` · **Category:** agent · **Status:** experimental
- **Import:** `import { RunHeader, RunHeaderProgress, RunHeaderTokens } from "@kura-ui/react/run-header";`
- **Docs:** https://kuro.abstergo.fyi/components/run-header
- **Registry item:** https://kuro.abstergo.fyi/r/run-header.json
- **Tags:** agent, run, session, header, status, cost, budget, tokens, timer, stop

## Install

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

## When to use

- The top of a page or pane that shows one agent session (Claude Code, Codex, Devin-style runs): what it is doing, how long, how much it costs, and a way to stop it.
- A dense status row above a run's transcript, plan or fleet (variant='bar').
- Showing spend against a per-run budget, with the meter turning amber at 80% and red past 100%.
- Giving the human Stop / Pause / Resume with keyboard shortcuts while an agent works.

## When not to use

- The run's step-by-step plan — use task-list (todo-style) or agent-timeline (steps with connectors).
- Parallel subagents inside a run — use agent-fleet.
- Context-window usage of one conversation — use context-meter.
- A single tool invocation — use tool-call.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `title` | `React.ReactNode` | — | yes | What the run is doing, e.g. "Migrate session API to @acme/auth". Truncates. |
| `agent` | `string` | — | no | Agent name, e.g. "Kura". Panel meta line only. |
| `model` | `string` | — | no | Model id in mono, e.g. "claude-opus-5-5". Panel meta line only. |
| `status` | `"queued" \| "running" \| "waiting" \| "done" \| "failed" \| "skipped" \| "paused"` | — | yes | Run state, drawn with StatusGlyph. running = blue arc + shimmering 'Running'; waiting = amber 'Waiting for you'; done = 'Completed'; failed = red; skipped = 'Stopped'. queued/running/waiting/paused keep the clock ticking. |
| `startedAt` | `Date \| number` | — | no | Run start. Drives the live elapsed clock (m:ss, h:mm:ss). Without it the clock shows –:––. |
| `endedAt` | `Date \| number` | — | no | Run end. Freezes the clock at endedAt − startedAt (use for finished or persisted runs). |
| `tokens` | `{ input: number; output: number }` | — | no | Token usage. Panel shows "412k in · 38.1k out"; bar shows the total. |
| `cost` | `number` | — | no | Spend so far in USD, formatted $1.82. |
| `budget` | `number` | — | no | Budget in USD. Shows '$1.82 of $5.00' with a 4px meter; amber from 80%, red (and red cost) past 100%. |
| `branch` | `string` | — | no | Git branch in mono with a branch icon. In the bar it shows from ~768px container width. |
| `progress` | `{ done: number; total: number }` | — | no | Plan progress: '4 of 7' plus a segmented bar (continuous above 24 steps). The current segment is blue while running, amber while waiting, red when failed. |
| `actions` | `React.ReactNode` | — | no | Extra controls before Pause/Stop, e.g. an 'Open PR' Button once the run is done. |
| `onStop` | `() => void` | — | no | Shows Stop while the run is live (queued, running, waiting, paused). Bound to ⌘/Ctrl+. |
| `onPause` | `() => void` | — | no | Shows Pause while running. Bound to ⌘/Ctrl+Shift+P. |
| `onResume` | `() => void` | — | no | Shows Resume while paused. Bound to ⌘/Ctrl+Shift+P. |
| `variant` | `"bar" \| "panel"` | `"panel"` | no | bar = one 44px row (glyph, title, status, branch, steps, tokens, cost, clock, controls; stats drop out as the container narrows). panel = title + meta line + a stats strip (Elapsed, Steps, Tokens, Spend). |
| `shortcuts` | `boolean` | `true` | no | Bind ⌘/Ctrl+. (Stop) and ⌘/Ctrl+Shift+P (Pause/Resume) on the document. Only one run header on screen should bind them. |

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

## Anatomy

- **RunHeader** (`data-slot="run-header"`) — Root <section> labelled by the title; `data-variant`, `data-status`. A size container.
- **Title** (`data-slot="run-header-title"`) — <h2>, truncated.
- **Status** (`data-slot="run-header-status"`) — Status word; shimmers while running, amber when waiting, red when failed.
- **Agent** (`data-slot="run-header-agent"`) — Agent name (panel).
- **Model** (`data-slot="run-header-model"`) — Model id in mono (panel).
- **Branch** (`data-slot="run-header-branch"`) — Branch icon + mono name.
- **Controls** (`data-slot="run-header-controls"`) — actions, then run-header-pause and run-header-stop.
- **Stats** (`data-slot="run-header-stats"`) — <dl>. In the panel each cell is run-header-stat with `data-stat` = elapsed | steps | tokens | cost, separated by hairlines.
- **Elapsed** (`data-slot="run-header-elapsed"`) — Mono tabular clock with reserved width so ticking never shifts layout.

## Accessibility

- Role: `region (section labelled by the title)`
- The stats are a <dl>: each value has a term (Elapsed, Steps, Tokens, Spend), visually hidden in the bar.
- A polite status region announces only status changes ('Run waiting for you'); the ticking clock and counters are not announced.
- Stop and Pause have tooltips with their shortcuts and aria-keyshortcuts. Status is never colour-only: the glyph shape and the status word carry it.
- The status glyph is decorative here (label=null) because the status word sits next to it.
- Reduced motion: The running arc, the current step's pulse and the status shimmer stop; meters change width without transition.

| Keys | Action |
| --- | --- |
| Mod+. | Stop the run (when onStop is set and the run is live) |
| Mod+Shift+P | Pause or resume |
| Tab | Actions, Pause, Stop |

## Notes for agents

- Keep one RunHeader mounted for the life of a run and update props; pass startedAt from the server so reloads keep the right clock, and endedAt once it finishes.
- Set shortcuts={false} on every RunHeader except the one for the focused run, otherwise ⌘. stops all of them.
- Map harness states: in-progress → running; needs approval / input → waiting; interrupted by the user → skipped ('Stopped'); error → failed.
- tokens.input should include cache reads if you want the number to match the bill; cost is whatever you computed — the component only formats it.
- Use the bar inside dense layouts (above a fleet or transcript) and the panel at the top of a run page.

## Examples

### Running (minimal)

Title, agent, model, status and a live clock.

```tsx
"use client";

import * as React from "react";
import { RunHeader } from "@kura-ui/react/run-header";

const minutesAgo = (m: number) => Date.now() - m * 60_000;

export function RunHeaderMinimal() {
  const [startedAt] = React.useState(() => minutesAgo(3.2));
  return (
    <RunHeader
      className="w-full max-w-2xl"
      title="Migrate session API to @acme/auth"
      agent="Kura"
      model="claude-opus-5-5"
      status="running"
      startedAt={startedAt}
      shortcuts={false}
    />
  );
}
```

### Live run (full)

Steps advance, tokens and spend climb against a $5 budget, the run waits for approval, then completes and offers Open PR. Pause, Resume and Stop work (⌘. and ⌘⇧P).

```tsx
"use client";

import { GitPullRequestArrow } from "lucide-react";
import * as React from "react";
import { Button } from "@kura-ui/react/button";
import type { AgentStatus } from "@kura-ui/react/status-glyph";
import { RunHeader } from "@kura-ui/react/run-header";

const minutesAgo = (m: number) => Date.now() - m * 60_000;

const SCRIPT: { status: AgentStatus; done: number; input: number; output: number; ms: number }[] = [
  { status: "running", done: 4, input: 268_400, output: 21_900, ms: 1800 },
  { status: "running", done: 4, input: 297_100, output: 24_300, ms: 1600 },
  { status: "waiting", done: 4, input: 301_800, output: 25_000, ms: 2600 },
  { status: "running", done: 5, input: 338_200, output: 29_400, ms: 1800 },
  { status: "running", done: 6, input: 376_900, output: 33_800, ms: 2000 },
  { status: "running", done: 7, input: 412_300, output: 38_100, ms: 1400 },
  { status: "done", done: 7, input: 412_300, output: 38_100, ms: 0 },
];

const priceOf = (input: number, output: number) => (input * 2.5 + output * 20) / 1_000_000 + 0.03;

export function RunHeaderFull() {
  const [startedAt] = React.useState(() => minutesAgo(11.4));
  const [beat, setBeat] = React.useState(0);
  const [override, setOverride] = React.useState<AgentStatus | null>(null);
  const [endedAt, setEndedAt] = React.useState<number | undefined>();
  const step = SCRIPT[Math.min(beat, SCRIPT.length - 1)] as (typeof SCRIPT)[number];
  const status = override ?? step.status;

  // biome-ignore lint/correctness/useExhaustiveDependencies: re-arm the timer on every beat
  React.useEffect(() => {
    if (override != null || step.ms === 0) return;
    const t = setTimeout(() => setBeat((b) => Math.min(b + 1, SCRIPT.length - 1)), step.ms);
    return () => clearTimeout(t);
  }, [beat, override, step.ms]);

  React.useEffect(() => {
    if ((status === "done" || status === "skipped") && endedAt == null) setEndedAt(Date.now());
  }, [status, endedAt]);

  return (
    <RunHeader
      className="w-full max-w-3xl"
      title="Migrate session API to @acme/auth"
      agent="Kura"
      model="claude-opus-5-5"
      branch="kura/auth-client"
      status={status}
      startedAt={startedAt}
      endedAt={endedAt}
      progress={{ done: step.done, total: 7 }}
      tokens={{ input: step.input, output: step.output }}
      cost={priceOf(step.input, step.output)}
      budget={5}
      onPause={() => setOverride("paused")}
      onResume={() => setOverride(null)}
      onStop={() => setOverride("skipped")}
      actions={
        status === "done" ? (
          <Button size="sm" variant="primary" className="animate-kura-fade-in">
            <GitPullRequestArrow />
            Open PR
          </Button>
        ) : null
      }
    />
  );
}
```

### Bar (variant)

One dense row per run: running, waiting for you, failed and completed.

```tsx
"use client";

import * as React from "react";
import { RunHeader } from "@kura-ui/react/run-header";

export function RunHeaderBar() {
  const [t] = React.useState(() => Date.now());
  return (
    <div className="flex w-full max-w-3xl flex-col gap-2">
      <RunHeader
        variant="bar"
        title="Migrate session API to @acme/auth"
        status="running"
        branch="kura/auth-client"
        startedAt={t - 8 * 60_000 - 42_000}
        progress={{ done: 4, total: 7 }}
        tokens={{ input: 268_400, output: 21_900 }}
        cost={1.12}
        budget={5}
        onPause={() => {}}
        onStop={() => {}}
        shortcuts={false}
      />
      <RunHeader
        variant="bar"
        title="Patch src/middleware.ts"
        status="waiting"
        branch="kura/auth-client"
        startedAt={t - 9 * 60_000 - 5_000}
        progress={{ done: 4, total: 7 }}
        tokens={{ input: 301_800, output: 25_000 }}
        cost={1.31}
        budget={5}
        onStop={() => {}}
        shortcuts={false}
      />
      <RunHeader
        variant="bar"
        title="Fix login.test.ts › refreshes an expired session"
        status="failed"
        branch="kura/auth-client"
        startedAt={t - 14 * 60_000}
        endedAt={t - 2 * 60_000 - 51_000}
        progress={{ done: 5, total: 7 }}
        tokens={{ input: 356_000, output: 31_200 }}
        cost={1.58}
        budget={5}
      />
      <RunHeader
        variant="bar"
        title="Bump @acme/auth to 2.4.0"
        status="done"
        branch="kura/auth-client"
        startedAt={t - 31 * 60_000}
        endedAt={t - 19 * 60_000 - 6_000}
        progress={{ done: 7, total: 7 }}
        tokens={{ input: 412_300, output: 38_100 }}
        cost={1.82}
        budget={5}
      />
    </div>
  );
}
```

### With agent-fleet (composition)

A bar header above the run's subagents.

```tsx
"use client";

import * as React from "react";
import { AgentFleet, type FleetAgent } from "@kura-ui/react/agent-fleet";
import { RunHeader } from "@kura-ui/react/run-header";

const minutesAgo = (m: number) => Date.now() - m * 60_000;

const FLEET: FleetAgent[] = [
  {
    id: "explorer",
    name: "explorer",
    role: "Maps call sites",
    status: "done",
    activity: "Found 23 calls to fetchUser() in 9 files",
    startedAt: minutesAgo(9),
    endedAt: minutesAgo(7.4),
    tokens: 84_200,
    cost: 0.21,
  },
  {
    id: "test-writer",
    name: "test-writer",
    role: "Updates tests",
    status: "running",
    activity: "Rewriting mocks in src/auth/__tests__/login.test.ts",
    progress: 0.62,
    startedAt: minutesAgo(3.1),
    tokens: 51_600,
    cost: 0.14,
  },
  {
    id: "reviewer",
    name: "reviewer",
    role: "Reviews the diff",
    status: "queued",
    activity: "Starts after test-writer",
  },
];

export function RunHeaderComposition() {
  const [startedAt] = React.useState(() => minutesAgo(9.6));
  return (
    <div className="flex w-full max-w-3xl flex-col gap-2">
      <RunHeader
        variant="bar"
        title="Migrate session API to @acme/auth"
        status="running"
        branch="kura/auth-client"
        startedAt={startedAt}
        progress={{ done: 5, total: 7 }}
        tokens={{ input: 338_200, output: 29_400 }}
        cost={1.46}
        budget={5}
        onPause={() => {}}
        onStop={() => {}}
        shortcuts={false}
      />
      <AgentFleet
        agents={FLEET}
        density="compact"
        defaultSelectedId="test-writer"
        onSelect={() => {}}
      />
    </div>
  );
}
```

## Dependencies

- npm: `lucide-react`
- Kura registry items: `kura-theme`, `button`, `icon-button`, `kura-format`, `shimmer-text`, `status-glyph`, `tooltip`, `use-elapsed`, `use-hotkey`, `utils`
- Related: `agent-fleet`, `task-list`, `checkpoints`, `context-meter`, `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:** primitives · **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 a GPU visual inside a component, such as the agent orb.
- A custom decorative shader behind a hero, card or voice surface.

## When not to use

- A voice-agent sphere — use agent-orb.
- 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 sunken neutral surface with one soft accent-subtle wash (tokens, follows the theme; `data-slot="shader-canvas-fallback"`). |
| `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.
- **DefaultFallback** (`data-slot="shader-canvas-fallback"`) — Rendered only when WebGL2 fails and no `fallback` is passed: a neutral token gradient with a soft accent wash.

## 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.125, 0.425, 0.905); // Kura blue, sRGB
  vec3 b = vec3(0.054, 0.061, 0.071); // graphite
  float t = 0.5 + 0.5 * sin(u_time * 0.5 + uv.x * 2.2 + uv.y * 1.4);
  fragColor = vec4(mix(a, b, smoothstep(0.0, 1.0, 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 < 3; 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) * 1.4;
  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.25, 0.75, f));
  col = mix(col, u_colorC, 0.6 * smoothstep(0.75, 1.05, length(q)));
  col += 0.012 * (hash(gl_FragCoord.xy) - 0.5); // dither
  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.054, 0.061, 0.071],
          u_colorB: [0.15, 0.25, 0.46],
          u_colorC: [0.62, 0.68, 0.78],
        }}
        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_signal;
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;

  // Graphite base with a slow blue 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_signal * 0.55, halo * 0.45);

  // 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_signal, clamp(glow * 0.4, 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 < 3; 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) * 1.4;
  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.25, 0.75, f));
  col = mix(col, u_colorC, 0.6 * smoothstep(0.75, 1.05, length(q)));
  col += 0.012 * (hash(gl_FragCoord.xy) - 0.5); // dither
  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.036, 0.04, 0.044],
            u_signal: [0.125, 0.425, 0.905],
            u_mist: [0.814, 0.879, 0.948],
          }}
          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: `agent-orb`

---

# 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-xl bg-kura-surface-raised px-3.5 py-3 text-sm leading-6 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-xl bg-kura-surface-raised px-3.5 py-3 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

> Quiet ring spinner (faint track, turning quarter arc) for indeterminate loading; 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: The arc stops rotating and the whole ring gently pulses in opacity instead.

## 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`

---

# Status Glyph

> Internal status glyph shared by agent surfaces: queued, running, waiting on you, done, failed, skipped and paused, drawn crisply in SVG.

- **Slug:** `status-glyph` · **Category:** primitives · **Status:** beta
- **Import:** `import { AgentStatus, StatusGlyph } from "@kura-ui/react/status-glyph";`
- **Docs:** https://kuro.abstergo.fyi/components/status-glyph
- **Registry item:** https://kuro.abstergo.fyi/r/status-glyph.json
- **Tags:** status, agent, glyph, internal

## Install

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

## When to use

- Inside an agent surface (task list, fleet, trace, run header) to show the state of a run, step or subagent the same way everywhere.

## When not to use

- A whole tool invocation with arguments and a timer — use tool-call.
- A general loading indicator with no agent state — use thinking-indicator.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `status` | `"queued" \| "running" \| "waiting" \| "done" \| "failed" \| "skipped" \| "paused"` | — | yes | The state to draw. running = turning arc in the signal colour; waiting = amber ring with a pulsing dot (the agent needs you). |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | no | 14, 16 or 20px. |
| `label` | `string \| null` | — | no | Spoken text (role="img"). Default the state name, e.g. "Running". Pass null when adjacent text already states it. |

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

## Anatomy

- **StatusGlyph** (`data-slot="status-glyph"`) — Root span with `data-status`; contains one 16-unit SVG.

## Accessibility

- Has role="img" with the state as its name, unless label={null}, in which case it is aria-hidden.
- State is never conveyed by colour alone: each state has a distinct shape.
- Reduced motion: The running arc stops turning and the waiting dot stops pulsing.

## Notes for agents

- Use this rather than inventing per-component status dots, so all agent surfaces share one vocabulary.

## Examples

### Running (minimal)

```tsx
import { StatusGlyph } from "@kura-ui/react/status-glyph";

export function StatusGlyphMinimal() {
  return <StatusGlyph status="running" />;
}
```

### Every state and size (full)

```tsx
import { type AgentStatus, StatusGlyph } from "@kura-ui/react/status-glyph";

const STATES: AgentStatus[] = [
  "queued",
  "running",
  "waiting",
  "done",
  "failed",
  "skipped",
  "paused",
];

export function StatusGlyphFull() {
  return (
    <div className="grid grid-cols-[auto_repeat(3,auto)] items-center gap-x-6 gap-y-3 text-[13px]">
      {STATES.map((s) => (
        <div key={s} className="contents">
          <span className="text-kura-fg-muted capitalize">{s}</span>
          <StatusGlyph status={s} size="sm" />
          <StatusGlyph status={s} />
          <StatusGlyph status={s} size="lg" />
        </div>
      ))}
    </div>
  );
}
```

## Dependencies

- npm: none
- Kura registry items: `kura-theme`, `utils`
- Related: `task-list`, `agent-fleet`, `trace-waterfall`, `run-header`, `tool-call`

---

# 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 [complete, setComplete] = React.useState(false);

  // biome-ignore lint/correctness/useExhaustiveDependencies: `run` restarts the fake stream
  React.useEffect(() => {
    const controller = new AbortController();
    setText("");
    setStreaming(true);
    setComplete(false);
    (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={() => setComplete(true)}
        className="min-h-32"
      />
      <div className="flex h-6 items-center justify-between">
        <span className="text-kura-fg-subtle text-xs tabular-nums">
          {complete ? `Done · ${text.length} characters` : "Receiving tokens…"}
        </span>
        {complete && (
          <Button
            variant="ghost"
            size="xs"
            className="animate-kura-fade-in"
            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`

---

# Task List

> The agent's plan as a todo list: segmented progress, shimmering current task, live and final durations, failure details, sub-tasks and a folded Completed group.

- **Slug:** `task-list` · **Category:** agent · **Status:** beta
- **Import:** `import { TaskList, TaskListItem } from "@kura-ui/react/task-list";`
- **Docs:** https://kuro.abstergo.fyi/components/task-list
- **Registry item:** https://kuro.abstergo.fyi/r/task-list.json
- **Tags:** agent, plan, todo, tasks, checklist, progress, claude-code, run

## Install

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

## When to use

- Show the todo list a coding agent maintains while it works (Claude Code TodoWrite, Codex plan, Cursor tasks) in a run sidebar or panel.
- Give a dense, scannable answer to 'what is the agent doing and what is left?' — '3 of 7' plus one row per task.
- Let the user click a task to show its output or diff next to the list (`onSelect` + `selectedId`).
- Show a failed task with its reason (`detail`) and a task blocked on the human (`waiting`).

## When not to use

- A narrative step timeline with connectors and inline tool calls under each step — use agent-timeline.
- Parallel subagents working at the same time — use agent-fleet.
- Timing analysis of nested spans on a shared time axis — use trace-waterfall.
- A single tool invocation with arguments and result — use tool-call.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `items` | `readonly TaskListItem[]` | — | yes | The plan, in order. TaskListItem = { id, title, status: "queued" \| "running" \| "waiting" \| "done" \| "failed" \| "skipped" \| "paused", detail?, durationMs?, startedAt?, children? }. |
| `title` | `React.ReactNode` | `"Plan"` | no | Heading in the panel header (panel variant only). |
| `actions` | `React.ReactNode` | — | no | Controls on the right of the header, after the progress bar (e.g. an IconButton). |
| `variant` | `"panel" \| "plain"` | `"panel"` | no | panel = card with header, '3 of 7' and segmented progress; plain = rows only, for embedding in your own sidebar. |
| `collapseCompleted` | `boolean` | `true` | no | Fold the leading run of finished (done/skipped) items into a 'Completed (n)' row while work remains. Needs at least three finished items; a fully finished plan is shown in full. |
| `completedOpen` | `boolean` | — | no | Whether the Completed group is expanded (controlled). |
| `defaultCompletedOpen` | `boolean` | `false` | no | Initial expanded state of the Completed group when uncontrolled. |
| `onCompletedOpenChange` | `(open: boolean) => void` | — | no | Called when the Completed group is toggled. |
| `selectedId` | `string \| null` | — | no | Highlighted item (bg-kura-active plus a 2px accent bar). Purely visual; pair with onSelect. |
| `onSelect` | `(id: string, item: TaskListItem) => void` | — | no | Makes rows buttons (with Up/Down/Home/End navigation) and reports the clicked item. Without it rows are static. |
| `empty` | `React.ReactNode` | — | no | Content when `items` is empty. Default: a quiet 'No plan yet' state. |
| `label` | `string` | — | no | Accessible name of the list. Default: `title` when it is a string, else 'Plan'. |

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

## Anatomy

- **TaskList** (`data-slot="task-list"`) — Root. `data-variant`, `data-progress="done/total"`; contains a polite status region.
- **Header** (`data-slot="task-list-header"`) — h-10 header: title, mono 'n of m', segmented progress, actions.
- **Progress** (`data-slot="task-list-progress"`) — One 4px segment per top-level item, coloured by status (neutral done, blue running, amber waiting, red failed).
- **Completed** (`data-slot="task-list-completed"`) — The folded group of finished items. `data-state="open" | "closed"`; its button has aria-expanded.
- **Item** (`data-slot="task-list-item"`) — <li> with `data-status` and `data-selected`; the running item has aria-current="step".
- **Row** (`data-slot="task-list-row"`) — The row: StatusGlyph, title, detail, duration. A <button> when onSelect is set.
- **Title** (`data-slot="task-list-title"`) — Shimmers while running; muted when done; struck through when skipped. Status is spoken after it.
- **Detail** (`data-slot="task-list-detail"`) — Second line. Red for failed, amber for waiting, subtle otherwise.
- **Duration** (`data-slot="task-list-duration"`) — Mono, tabular, width-reserved. Live clock (0:42) while running, final duration (1m 12s) after.
- **Children** (`data-slot="task-list-children"`) — Nested <ul> of sub-tasks with a hairline guide; the parent shows 'done/total'.
- **Empty** (`data-slot="task-list-empty"`) — Rendered when there are no items.

## Accessibility

- Role: `list`
- A <ul> labelled by `label`/`title`; each item speaks its status after the title (“Run pnpm test (failed)”), and the running item has aria-current="step".
- A polite status region announces the current task (“Task 4 of 7: Patch src/middleware.ts”), a failure, “Waiting for you” or “All tasks complete”. Live timers are never announced.
- With onSelect, rows are buttons with aria-pressed reflecting selectedId; the Completed toggle has aria-expanded/aria-controls.
- Status is never colour-only: the glyph shape and the spoken status carry it.
- Reduced motion: Rows fade in without rising, the title shimmer and running segment pulse stop, and the chevron turns without animating.

| Keys | Action |
| --- | --- |
| Tab | Moves into the list (rows are buttons when onSelect is set). |
| ArrowDown / ArrowUp | Moves focus to the next / previous row. |
| Home / End | Moves focus to the first / last row. |
| Enter / Space | Selects the focused task, or toggles the Completed group. |

## Notes for agents

- Map a model-maintained todo list directly: pending → queued, in_progress → running, completed → done. Keep ids stable so rows don't remount.
- Pass `startedAt` for the running item (from your server) so the live timer survives reloads; pass `durationMs` once it finishes.
- Only one top-level item should be `running`; it carries the blue signal and the shimmer.
- Use `waiting` (amber) only when the agent is blocked on the human, and put the ask in `detail`.
- The Completed fold only collapses the *leading* finished items, so a failed task in the middle is never hidden.

## Examples

### A plan in progress (minimal)

Two done, one running with a live timer, one queued.

```tsx
import { TaskList } from "@kura-ui/react/task-list";

export function TaskListMinimal() {
  return (
    <TaskList
      className="w-full max-w-md"
      items={[
        { id: "read", title: "Read routes in src/app", status: "done", durationMs: 21_400 },
        { id: "map", title: "Map call sites of fetchUser()", status: "done", durationMs: 48_200 },
        {
          id: "patch",
          title: "Patch src/auth/client.ts",
          status: "running",
          startedAt: Date.now() - 34_000,
        },
        { id: "test", title: "Run pnpm test", status: "queued" },
      ]}
    />
  );
}
```

### Live run (full)

The auth-client migration plays out: finished tasks fold into Completed, sub-tasks tick, the test run fails, a fix task appears, the re-run passes, the reviewer signs off and the PR opens.

```tsx
"use client";

import { RotateCcw } from "lucide-react";
import * as React from "react";
import { IconButton } from "@kura-ui/react/icon-button";
import { TaskList, type TaskListItem } from "@kura-ui/react/task-list";

const PLAN: TaskListItem[] = [
  { id: "routes", title: "Read routes in src/app", status: "done", durationMs: 21_400 },
  {
    id: "map",
    title: "Map call sites of fetchUser()",
    status: "done",
    durationMs: 48_200,
    detail: "14 call sites across 9 files",
  },
  {
    id: "client",
    title: "Patch src/auth/client.ts",
    status: "done",
    durationMs: 72_900,
  },
  { id: "middleware", title: "Patch src/middleware.ts", status: "running" },
  {
    id: "tests",
    title: "Update tests",
    status: "queued",
    children: [
      { id: "tests-login", title: "login.test.ts", status: "queued" },
      { id: "tests-session", title: "session.test.ts", status: "queued" },
    ],
  },
  { id: "run", title: "Run pnpm test", status: "queued" },
  { id: "review", title: "Review the diff", status: "queued" },
  { id: "pr", title: "Open pull request", status: "queued" },
];

function set(items: TaskListItem[], id: string, patch: Partial<TaskListItem>): TaskListItem[] {
  return items.map((item) =>
    item.id === id
      ? { ...item, ...patch }
      : item.children
        ? { ...item, children: set([...item.children], id, patch) }
        : item,
  );
}

const SCRIPT: Beat[] = [
  {
    at: 2600,
    patch: (s) =>
      set(
        set(set(s, "middleware", { status: "done", durationMs: 41_300 }), "tests", {
          status: "running",
          startedAt: Date.now(),
        }),
        "tests-login",
        { status: "running", startedAt: Date.now() },
      ),
  },
  {
    at: 4400,
    patch: (s) =>
      set(set(s, "tests-login", { status: "done", durationMs: 18_200 }), "tests-session", {
        status: "running",
        startedAt: Date.now(),
      }),
  },
  {
    at: 6000,
    patch: (s) =>
      set(
        set(set(s, "tests-session", { status: "done", durationMs: 12_700 }), "tests", {
          status: "done",
          durationMs: 30_900,
        }),
        "run",
        { status: "running", startedAt: Date.now(), detail: "pnpm test --filter @acme/web" },
      ),
  },
  {
    at: 8400,
    patch: (s) =>
      insertAfter(
        set(s, "run", {
          status: "failed",
          durationMs: 38_400,
          detail: "login.test.ts › refreshes an expired session — expected 200, received 401",
        }),
        "run",
        {
          id: "fix",
          title: "Retry refresh with the rotated token",
          status: "running",
          startedAt: Date.now(),
          detail: "src/auth/client.ts:88",
        },
      ),
  },
  {
    at: 11_000,
    patch: (s) =>
      set(set(s, "fix", { status: "done", durationMs: 52_100, detail: undefined }), "run", {
        status: "running",
        startedAt: Date.now(),
        detail: "pnpm test --filter @acme/web",
      }),
  },
  {
    at: 13_200,
    patch: (s) =>
      set(set(s, "run", { status: "done", durationMs: 36_800, detail: "142 passed" }), "review", {
        status: "running",
        startedAt: Date.now(),
        detail: "reviewer subagent",
      }),
  },
  {
    at: 15_400,
    patch: (s) =>
      set(
        set(s, "review", { status: "done", durationMs: 186_000, detail: "2 nits, 0 blocking" }),
        "pr",
        { status: "running", startedAt: Date.now() },
      ),
  },
  {
    at: 17_000,
    patch: (s) => set(s, "pr", { status: "done", durationMs: 48_100, detail: "acme/web#482" }),
  },
];

function insertAfter(items: TaskListItem[], id: string, next: TaskListItem): TaskListItem[] {
  const i = items.findIndex((item) => item.id === id);
  return [...items.slice(0, i + 1), next, ...items.slice(i + 1)];
}

export function TaskListFull() {
  const [items, setItems] = React.useState<TaskListItem[]>(() =>
    set(PLAN, "middleware", { startedAt: Date.now() - 27_000 }),
  );
  const [selectedId, setSelectedId] = React.useState<string | null>(null);
  const [run, setRun] = React.useState(0);

  // biome-ignore lint/correctness/useExhaustiveDependencies: `run` replays the script
  React.useEffect(() => {
    setItems(set(PLAN, "middleware", { startedAt: Date.now() - 27_000 }));
    const timers = SCRIPT.map((beat) => setTimeout(() => setItems(beat.patch), beat.at));
    return () => timers.forEach(clearTimeout);
  }, [run]);

  return (
    <TaskList
      className="w-full max-w-md"
      items={items}
      label="Migrate to @acme/auth client"
      selectedId={selectedId}
      onSelect={(id) => setSelectedId((cur) => (cur === id ? null : id))}
      actions={
        <IconButton
          label="Replay"
          icon={<RotateCcw />}
          variant="ghost"
          size="xs"
          className="-mr-1.5"
          onClick={() => setRun((r) => r + 1)}
        />
      }
    />
  );
}
```

### Every state (state)

Done, skipped, waiting for approval, failed with a reason, paused and queued.

```tsx
import { TaskList } from "@kura-ui/react/task-list";

export function TaskListStates() {
  return (
    <TaskList
      className="w-full max-w-md"
      title="Release checklist"
      collapseCompleted={false}
      items={[
        { id: "a", title: "Bump version to 2.4.0", status: "done", durationMs: 3_200 },
        {
          id: "b",
          title: "Regenerate API types",
          status: "skipped",
          detail: "Schema unchanged since 2.3.1",
        },
        {
          id: "c",
          title: "Run database migration 0042_sessions",
          status: "waiting",
          detail: "Needs your approval — touches production",
        },
        {
          id: "d",
          title: "Build preview deployment",
          status: "failed",
          durationMs: 84_100,
          detail: "next build exited with code 1 — Type error in src/middleware.ts:31",
        },
        { id: "e", title: "Notify #releases", status: "paused" },
        { id: "f", title: "Tag release", status: "queued" },
      ]}
    />
  );
}
```

### Plan beside output (composition)

The plain variant in a sidebar; selecting a task shows its output on the right.

```tsx
"use client";

import * as React from "react";
import { TaskList, type TaskListItem } from "@kura-ui/react/task-list";

const OUTPUT: Record<string, string[]> = {
  routes: [
    "$ rg --files src/app | rg route",
    "src/app/api/session/route.ts",
    "src/app/login/page.tsx",
    "src/app/(app)/layout.tsx",
  ],
  map: [
    "explorer · 14 call sites of fetchUser()",
    "src/app/(app)/layout.tsx:12",
    "src/components/nav/user-menu.tsx:8",
    "src/lib/server/session.ts:44",
    "… 11 more",
  ],
  client: [
    "Edited src/auth/client.ts  +64 −22",
    "Replaced legacy REST session calls",
    "with createAuthClient({ baseUrl })",
  ],
  run: [
    "$ pnpm test",
    "✕ login.test.ts › refreshes an expired session",
    "  expected 200, received 401",
    "141 passed, 1 failed (38.4s)",
  ],
};

export function TaskListComposition() {
  const [selectedId, setSelectedId] = React.useState("run");
  const [t0] = React.useState(() => Date.now());
  const items: TaskListItem[] = [
    { id: "routes", title: "Read routes", status: "done", durationMs: 21_400 },
    { id: "map", title: "Map fetchUser() calls", status: "done", durationMs: 48_200 },
    { id: "client", title: "Patch auth client", status: "done", durationMs: 72_900 },
    {
      id: "run",
      title: "Run pnpm test",
      status: "failed",
      durationMs: 38_400,
      detail: "1 failed",
    },
    { id: "fix", title: "Fix token refresh", status: "running", startedAt: t0 - 19_000 },
  ];
  const lines = OUTPUT[selectedId] ?? ["No output yet."];
  return (
    <div className="grid w-full max-w-2xl overflow-hidden rounded-kura-xl bg-kura-surface shadow-kura-sm sm:grid-cols-[240px_1fr]">
      <div className="border-kura-border-subtle border-b sm:border-r sm:border-b-0">
        <div className="flex h-10 items-center px-3.5 font-medium text-[13px]">Plan</div>
        <TaskList
          variant="plain"
          collapseCompleted={false}
          items={items}
          selectedId={selectedId}
          onSelect={(id) => setSelectedId(id)}
          label="Plan"
        />
      </div>
      <div className="flex min-w-0 flex-col">
        <div className="flex h-10 items-center gap-2 border-kura-border-subtle border-b px-3.5">
          <span className="truncate font-medium text-[13px]">
            {items.find((i) => i.id === selectedId)?.title}
          </span>
          <span className="ml-auto font-kura-mono text-[12px] text-kura-fg-subtle">output</span>
        </div>
        <pre className="m-0 min-h-40 flex-1 overflow-auto bg-kura-surface-sunken px-3.5 py-3 font-kura-mono text-[12px] text-kura-fg-muted leading-5">
          {lines.join("\n")}
        </pre>
      </div>
    </div>
  );
}
```

## Dependencies

- npm: `lucide-react`
- Kura registry items: `kura-theme`, `kura-format`, `shimmer-text`, `status-glyph`, `use-controllable-state`, `use-elapsed`, `utils`
- Related: `agent-timeline`, `agent-fleet`, `run-header`, `trace-waterfall`, `status-glyph`

---

# Terminal

> Streamed command output that behaves like a real terminal: ANSI colours, progress-bar rewrites, stick-to-bottom, live clock and exit-code badge.

- **Slug:** `terminal` · **Category:** workspace · **Status:** experimental
- **Import:** `import { AnsiColor, AnsiScreen, AnsiSpan, AnsiStyle, Terminal, TerminalStatus } from "@kura-ui/react/terminal";`
- **Docs:** https://kuro.abstergo.fyi/components/terminal
- **Registry item:** https://kuro.abstergo.fyi/r/terminal.json
- **Tags:** terminal, shell, logs, ansi, streaming, command, agent, workspace

## Install

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

## When to use

- Show a shell command an agent ran (pnpm test, git status, a build) with its output, while it runs and after.
- Stream a child process's stdout (AsyncIterable<string>) or a growing log string into the UI.
- Long logs where the tail matters: collapse to the last N lines with “Show all N lines”.
- A dev-server or watcher log with a Stop control in the header.

## When not to use

- Source code or a snippet to copy — use code-block.
- Reviewing file edits — use diff-view.
- A tool call whose output is structured JSON — use tool-call.
- Interactive shells that take keyboard input — this renders output only (no PTY, no input line).

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `command` | `string` | — | no | The command, shown on the prompt line (`$ pnpm test`) and in the accessible name. |
| `lines` | `readonly string[] \| string` | — | no | Output as lines or one growing string. ANSI SGR (colours 30–37/90–97, 256/truecolour approximated, bold, dim, italic, underline, inverse) and cursor controls (\r, erase line, cursor up, backspace) are rendered; OSC titles/links are stripped. Append-only updates are parsed incrementally. |
| `stream` | `AsyncIterable<string>` | — | no | Output as a stream of chunks; takes precedence over `lines`. Chunks may split lines and escape sequences. Status is “running” until it ends. |
| `onStreamEnd` | `() => void` | — | no | Called once `stream` has ended. |
| `status` | `"idle" \| "running" \| "done" \| "failed"` | — | no | Lifecycle. Default: from exitCode (0 → done, otherwise failed), "running" while a stream is open, else "idle" (no glyph). |
| `exitCode` | `number \| null` | — | no | Exit code, shown as a badge once finished (red when non-zero). |
| `startedAt` | `Date \| number` | — | no | Start time for the live clock. Default: when status became running. |
| `duration` | `number` | — | no | Final duration in ms for persisted runs. Default: measured from running → finished in this session. |
| `cwd` | `string` | — | no | Working directory in the header, e.g. "~/acme/web". |
| `title` | `React.ReactNode` | — | no | Header title, e.g. "Run tests". Default: the cwd, or "Terminal". |
| `prompt` | `string` | `"$"` | no | Prompt glyph before the command. |
| `maxHeight` | `number` | `320` | no | Viewport height in px. Output sticks to the bottom while the user is there; scrolling up shows “Jump to latest” / “N new lines”. |
| `maxLines` | `number` | — | no | Collapse to the last N lines with a “Show all N lines” control at the top. |
| `expanded` | `boolean` | — | no | Showing every line past maxLines (controlled). |
| `defaultExpanded` | `boolean` | `false` | no | Initial expanded state when uncontrolled. |
| `onExpandedChange` | `(expanded: boolean) => void` | — | no | Called when “Show all” / “Show last N” is used. |
| `wrap` | `boolean` | `true` | no | Soft-wrap long lines. |
| `copyable` | `boolean` | `true` | no | Show the copy button: copies `$ command` plus the plain output (no escape codes). |
| `onCopy` | `(text: string) => void` | — | no | Called with the copied text after a successful copy. |
| `header` | `boolean` | `true` | no | Show the header row. |
| `actions` | `React.ReactNode` | — | no | Extra header controls before the copy button, e.g. a Stop Button. |

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

## Anatomy

- **Terminal** (`data-slot="terminal"`) — `data-status="idle" | "running" | "done" | "failed"`, `data-state="collapsed" | "expanded"` when maxLines applies.
- **Header** (`data-slot="terminal-header"`) — Status glyph, title (`terminal-title`), cwd, live clock / duration (`terminal-elapsed`), exit badge (`terminal-exit-code`), actions, copy.
- **Output** (`data-slot="terminal-output"`) — `role="log"` scroll viewport (aria-live off), keyboard-scrollable; prompt line (`terminal-command`) and lines (`terminal-line`).
- **Cursor** (`data-slot="terminal-cursor"`) — Block cursor at the live edge while running.
- **Expand** (`data-slot="terminal-expand"`) — “Show all N lines” row when collapsed (`terminal-collapse` to collapse again).
- **Jump** (`data-slot="terminal-jump"`) — Floating “Jump to latest” / “N new lines” pill when scrolled away from the bottom.

## Accessibility

- Role: `log`
- The output is a role=log region named “Output of <command>” with aria-live off, so streaming never floods a screen reader.
- A separate polite status announces only transitions: “pnpm test running”, “pnpm test failed, exit code 1”, and copy confirmation.
- The viewport is focusable (Tab) and scrolls with arrow keys / Page Up / Page Down.
- Status is text as well as colour: the exit badge reads “exit 1”; the glyph is decorative next to it.
- Reduced motion: The cursor stops pulsing, the running glyph stops spinning, and the copy icon swap and pill entrance become plain fades. Jump to latest still scrolls smoothly only if the browser allows it.

| Keys | Action |
| --- | --- |
| Tab | Focus the output, then the expand, jump, action and copy buttons |
| Arrow keys / Page Up / Page Down | Scroll the focused output |
| Enter / Space | Activate Show all / Jump to latest / Copy |

## Notes for agents

- Pass raw process output; don't strip ANSI codes. Escape sequences split across chunks are buffered.
- For a growing string, only append — replacing earlier text triggers a full re-parse (still correct, just slower).
- Keep the same Terminal mounted from running → done so the measured duration works; for history pass `duration`.
- `stream` is consumed once; create a new iterable to restart. Set `exitCode` in onStreamEnd to finish with a badge.
- Colours map to Kura tokens; override any of them with --kura-terminal-{red,green,yellow,blue,magenta,cyan,white,gray,black} on a parent.
- Helpers exported alongside: parseAnsi(text), stripAnsi(text), AnsiScreen (incremental).

## Examples

### Finished command (minimal)

`git status --short` with coloured output and an exit badge.

```tsx
import { Terminal } from "@kura-ui/react/terminal";

const red = (s: string) => `\x1b[31m${s}\x1b[39m`;

export function TerminalMinimal() {
  return (
    <Terminal
      className="w-full max-w-2xl"
      cwd="~/acme/web"
      command="git status --short"
      exitCode={0}
      lines={[
        ` ${red("M")} src/auth/client.ts`,
        ` ${red("M")} src/middleware.ts`,
        ` ${red("M")} src/auth/__tests__/login.test.ts`,
        ` ${red("D")} src/lib/legacy-session.ts`,
      ]}
    />
  );
}
```

### Streaming test run (full)

`pnpm test` streams vitest output line by line (live clock, cursor, stick-to-bottom), ends with one failing test and exit 1.

```tsx
"use client";

import * as React from "react";
import { Terminal } from "@kura-ui/react/terminal";

const TEST_OUTPUT = [
  "",
  `> @acme/web@0.42.0 test ${dim("/Users/kura/acme/web")}`,
  "> vitest run",
  "",
  ` ${badge("RUN", 36)} ${cyan("v3.2.4")} ${gray("/Users/kura/acme/web")}`,
  "",
  ` ${green("✓")} ${dim("src/auth/__tests__/")}session.test.ts ${gray("(6 tests)")} ${gray("41ms")}`,
  ` ${green("✓")} ${dim("src/")}middleware.test.ts ${gray("(4 tests)")} ${gray("18ms")}`,
  ` ${green("✓")} ${dim("src/routes/__tests__/")}account.test.ts ${gray("(9 tests)")} ${gray("112ms")}`,
  ` ${yellow("❯")} ${dim("src/auth/__tests__/")}login.test.ts ${gray("(5 tests | ")}${red("1 failed")}${gray(")")} ${gray("87ms")}`,
  `   ${green("✓")} login ${gray(">")} detects an expired session ${gray("2ms")}`,
  `   ${red("×")} login ${gray(">")} refreshes an expired session ${gray("14ms")}`,
  `     ${red("→ expected 'tok_expired' to be 'tok_next' // Object.is equality")}`,
  ` ${green("✓")} ${dim("src/lib/__tests__/")}http.test.ts ${gray("(7 tests)")} ${gray("9ms")}`,
  "",
  red(`⎯⎯⎯⎯⎯⎯⎯ ${bold("Failed Tests 1")} ⎯⎯⎯⎯⎯⎯⎯`),
  "",
  ` ${badge("FAIL", 31)} src/auth/__tests__/login.test.ts ${gray(">")} login ${gray(">")} refreshes an expired session`,
  `${red(bold("AssertionError"))}${red(": expected 'tok_expired' to be 'tok_next' // Object.is equality")}`,
  "",
  `${green("- Expected")}`,
  `${red("+ Received")}`,
  "",
  `${green("- tok_next")}`,
  `${red("+ tok_expired")}`,
  "",
  ` ${cyan("❯")} src/auth/__tests__/login.test.ts:18:32`,
  gray("     16|     const next = await refreshSession(session);"),
  gray('     17|     expect(next.user.id).toBe("u_1");'),
  `     18|     expect(next.refreshToken).toBe(${green('"tok_next"')});`,
  `       | ${red("                               ^")}`,
  "",
  ` ${dim("Test Files")}  ${bold(red("1 failed"))} ${gray("|")} ${bold(green("4 passed"))} ${gray("(5)")}`,
  `      ${dim("Tests")}  ${bold(red("1 failed"))} ${gray("|")} ${bold(green("30 passed"))} ${gray("(31)")}`,
  `   ${dim("Start at")}  14:02:11`,
  `   ${dim("Duration")}  1.42s ${gray("(transform 212ms, setup 0ms, collect 610ms, tests 267ms)")}`,
  "",
  `${red(" ELIFECYCLE ")} ${red("Test failed. See above for more details.")}`,
];

async function* replay(lines: string[], signal: { cancelled: boolean }) {
  for (const [i, line] of lines.entries()) {
    // Collection is slow, results arrive in bursts, the summary lands at once.
    const wait = i < 4 ? 260 : i < 14 ? 180 + (i % 3) * 140 : 35;
    await new Promise((r) => setTimeout(r, wait));
    if (signal.cancelled) return;
    yield `${line}\n`;
  }
}

const dim = (s: string) => `\x1b[2m${s}\x1b[22m`;

const bold = (s: string) => `\x1b[1m${s}\x1b[22m`;

const red = (s: string) => `\x1b[31m${s}\x1b[39m`;

const green = (s: string) => `\x1b[32m${s}\x1b[39m`;

const yellow = (s: string) => `\x1b[33m${s}\x1b[39m`;

const cyan = (s: string) => `\x1b[36m${s}\x1b[39m`;

const gray = (s: string) => `\x1b[90m${s}\x1b[39m`;

const badge = (s: string, color: 31 | 32 | 34 | 36) => `\x1b[1;7;${color}m ${s} \x1b[0m`;

export function TerminalFull() {
  const [stream, setStream] = React.useState<AsyncIterable<string>>();
  const [exitCode, setExitCode] = React.useState<number | null>(null);
  React.useEffect(() => {
    const signal = { cancelled: false };
    setStream(replay(TEST_OUTPUT, signal));
    return () => {
      signal.cancelled = true;
    };
  }, []);
  return (
    <Terminal
      className="w-full max-w-2xl"
      title="Run tests"
      cwd="~/acme/web"
      command="pnpm test"
      stream={stream}
      status={exitCode == null ? "running" : undefined}
      exitCode={exitCode}
      onStreamEnd={() => setExitCode(1)}
      maxHeight={360}
    />
  );
}
```

### Collapsed build log (state)

A Next.js build collapsed to the last 9 lines; one line is a \r-rewritten progress counter.

```tsx
import { Terminal } from "@kura-ui/react/terminal";

const BUILD_OUTPUT = [
  `   ${bold("▲ Next.js 16.0.1")}`,
  `   - Environments: .env.production`,
  "",
  `   Creating an optimized production build ...`,
  ` ${green("✓")} Compiled successfully in 8.4s`,
  ` ${green("✓")} Linting and checking validity of types`,
  ` ${green("✓")} Collecting page data`,
  // A progress line rewritten in place with carriage returns.
  `   Generating static pages (0/14)\r   Generating static pages (7/14)\r ${green("✓")} Generating static pages (14/14)`,
  ` ${green("✓")} Finalizing page optimization`,
  "",
  `${bold("Route (app)")}                         ${bold("Size")}  ${bold("First Load JS")}`,
  `┌ ○ /                              5.21 kB         ${green("112 kB")}`,
  `├ ○ /_not-found                       990 B         ${green("103 kB")}`,
  `├ ƒ /account                        3.84 kB         ${green("118 kB")}`,
  `├ ƒ /api/health                       142 B         ${green("102 kB")}`,
  `├ ○ /login                          2.67 kB         ${green("115 kB")}`,
  `└ ○ /signup                         2.71 kB         ${green("115 kB")}`,
  `+ First Load JS shared by all       ${green("102 kB")}`,
  "",
  `ƒ Middleware                        ${green("34.1 kB")}`,
  "",
  `○  (Static)   prerendered as static content`,
  `ƒ  (Dynamic)  server-rendered on demand`,
];

const bold = (s: string) => `\x1b[1m${s}\x1b[22m`;

const green = (s: string) => `\x1b[32m${s}\x1b[39m`;

export function TerminalCollapsed() {
  return (
    <Terminal
      className="w-full max-w-2xl"
      title="Build"
      cwd="~/acme/web"
      command="pnpm build"
      lines={BUILD_OUTPUT}
      exitCode={0}
      duration={23_400}
      maxLines={9}
      wrap={false}
    />
  );
}
```

### Dev server with Stop (composition)

A Button in `actions` stops a dev server that keeps logging.

```tsx
"use client";

import { Square } from "lucide-react";
import * as React from "react";
import { Button } from "@kura-ui/react/button";
import { Terminal } from "@kura-ui/react/terminal";

const green = (s: string) => `\x1b[32m${s}\x1b[39m`;

const DEV_LINES = [
  `  ${bold("▲ Next.js 16.0.1")} (Turbopack)`,
  `  - Local:        ${cyan("http://localhost:3000")}`,
  `  - Network:      ${cyan("http://192.168.1.24:3000")}`,
  "",
  ` ${green("✓")} Starting...`,
  ` ${green("✓")} Ready in 1.1s`,
  ` ${gray("○")} Compiling /login ...`,
  ` ${green("✓")} Compiled /login in 640ms`,
  ` GET /login ${green("200")} in 702ms`,
  ` POST /api/auth/session ${green("200")} in 48ms`,
  ` GET /account ${green("200")} in 131ms`,
  ` GET /api/auth/session ${yellow("401")} in 12ms`,
  ` GET /login?next=%2Faccount ${green("200")} in 22ms`,
];

const bold = (s: string) => `\x1b[1m${s}\x1b[22m`;

const yellow = (s: string) => `\x1b[33m${s}\x1b[39m`;

const cyan = (s: string) => `\x1b[36m${s}\x1b[39m`;

const gray = (s: string) => `\x1b[90m${s}\x1b[39m`;

export function TerminalComposition() {
  const [lines, setLines] = React.useState<string[]>(DEV_LINES.slice(0, 6));
  const [stopped, setStopped] = React.useState(false);
  React.useEffect(() => {
    if (stopped) return;
    const id = setInterval(() => {
      setLines((prev) =>
        prev.length < DEV_LINES.length
          ? [...prev, DEV_LINES[prev.length]!]
          : [...prev, ` GET /api/health ${green("200")} in ${4 + (prev.length % 7)}ms`],
      );
    }, 1400);
    return () => clearInterval(id);
  }, [stopped]);
  return (
    <Terminal
      className="w-full max-w-2xl"
      title="Dev server"
      cwd="~/acme/web"
      command="pnpm dev"
      lines={stopped ? [...lines, "^C"] : lines}
      status={stopped ? "done" : "running"}
      maxHeight={240}
      actions={
        !stopped && (
          <Button size="xs" variant="ghost" onClick={() => setStopped(true)}>
            <Square aria-hidden className="size-3 fill-current" />
            Stop
          </Button>
        )
      }
    />
  );
}
```

## Dependencies

- npm: `lucide-react`
- Kura registry items: `kura-theme`, `icon-button`, `kura-format`, `status-glyph`, `use-controllable-state`, `use-elapsed`, `utils`
- Related: `diff-view`, `file-changes`, `code-block`, `tool-call`, `agent-timeline`

---

# 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 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 blue default when it means “the model is working”; use a neutral grey for secondary, low-priority activity.
- 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-surface-sunken text-kura-fg-muted shadow-kura-xs">
        <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`, `agent-orb`, `streaming-text`, `message`, `run-header`

---

# 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 = blue pulse + shimmering title + ticking timer; success = check; error = cross (details open by default); awaiting-approval = blue 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"
      />
      {status === "success" && (
        <Button
          variant="ghost"
          size="xs"
          className="animate-kura-fade-in self-end"
          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`, `status-glyph`, `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`

---

# Trace Waterfall

> Span tree on a shared time axis for agent runs: nested agent, LLM, tool and retrieval spans, live bars, a details row and keyboard tree navigation.

- **Slug:** `trace-waterfall` · **Category:** agent · **Status:** beta
- **Import:** `import { TraceSpan, TraceSpanKind, TraceWaterfall } from "@kura-ui/react/trace-waterfall";`
- **Docs:** https://kuro.abstergo.fyi/components/trace-waterfall
- **Registry item:** https://kuro.abstergo.fyi/r/trace-waterfall.json
- **Tags:** agent, trace, observability, spans, waterfall, timeline, tokens, latency

## Install

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

## When to use

- Show where the time (and tokens, and money) went in an agent run: which model calls, tool calls and subagents ran, nested, and when.
- Debug a slow or failed run: spot the long LLM call, the failed `pnpm test`, the subagent that ran in parallel.
- Watch a run live: running spans grow against the axis and a 'now' line moves (pass `startedAt` or drive `now`).
- Inspect one span's input, output, error, model, tokens and cost inline by selecting it.

## When not to use

- The agent's plan or todo list (what it intends to do) — use task-list.
- A narrative of steps with tool calls attached — use agent-timeline.
- Parallel subagents as a live roster with activity and progress — use agent-fleet.
- A single tool invocation — use tool-call.

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `spans` | `readonly TraceSpan[]` | — | yes | Root spans (usually one agent span). TraceSpan = { id, name, kind: "agent" \| "llm" \| "tool" \| "retrieval", start (ms since run start), end? (omit while running), status: AgentStatus, meta? (mono hint: path, command), model?, tokens? { input, output }, cost? (USD), input?, output?, error?, children? }. |
| `title` | `React.ReactNode` | `"Trace"` | no | Header title. |
| `actions` | `React.ReactNode` | — | no | Controls on the right of the header (e.g. a replay or open-in-LangSmith button). |
| `now` | `number` | — | no | Current run time in ms since start (a controlled clock). Running spans end here and the 'now' line sits here. Use it for replays and server-driven clocks. |
| `startedAt` | `Date \| number` | — | no | Wall-clock start of the run. When given (and `now` isn't), running spans grow live, ticking every 250ms. Without either, running spans end at the latest known time. |
| `selectedId` | `string \| null` | — | no | Selected span (controlled). Its details row opens under it. |
| `defaultSelectedId` | `string \| null` | `null` | no | Initially selected span when uncontrolled. May name a span that doesn't exist yet; it opens when the span appears. |
| `onSelectedIdChange` | `(id: string \| null) => void` | — | no | Called when a span is selected, or with null when the selection is cleared. |
| `defaultCollapsedIds` | `readonly string[]` | — | no | Spans whose subtrees start collapsed (e.g. noisy subagents). |
| `renderDetails` | `(span: TraceSpan) => React.ReactNode` | — | no | Replace the details row body for a span (e.g. a CodeBlock with the diff a tool wrote). Return null to use the default stats + input/output. |
| `empty` | `React.ReactNode` | — | no | Rendered when there are no spans. Default: 'No spans yet'. |
| `label` | `string` | `"Trace"` | no | Accessible name of the tree. |

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

## Anatomy

- **TraceWaterfall** (`data-slot="trace-waterfall"`) — Root panel, a container-query context. `data-state="running" | "idle"`; contains a polite status region.
- **Header** (`data-slot="trace-waterfall-header"`) — h-10 header: title, summary, actions.
- **Summary** (`data-slot="trace-waterfall-summary"`) — Mono: span count · total duration · tokens · cost. Count/tokens/cost hide on narrow containers.
- **Axis** (`data-slot="trace-waterfall-axis"`) — Sticky row with 'Span / Duration' over the tree and nice tick labels (0, 2m, 4m…) over the bars.
- **Body** (`data-slot="trace-waterfall-body"`) — Scroll container. Give the root a height (e.g. `h-[480px]`) to scroll long traces under the sticky axis.
- **Span** (`data-slot="trace-waterfall-span"`) — role="treeitem" with `data-kind`, `data-status`, `data-selected`; wraps the row and, when selected, its details.
- **Row** (`data-slot="trace-waterfall-row"`) — h-8 grid row: indented tree cell (chevron, kind icon, name, mono meta, glyph for running/failed/waiting, duration) and the bar cell.
- **Toggle** (`data-slot="trace-waterfall-toggle"`) — Chevron that collapses a subtree (pointer only; ArrowLeft/Right on the keyboard).
- **Bar** (`data-slot="trace-waterfall-bar"`) — Positioned on the shared axis. Neutral greys by kind (LLM darkest), thin for agent spans; blue while running, red failed, amber waiting, ink when selected.
- **Now** (`data-slot="trace-waterfall-now"`) — Hairline at the current time while any span is running.
- **Details** (`data-slot="trace-waterfall-details"`) — Sunken row under the selected span: kind, start, duration, model, tokens, cost, then input and output/error.
- **Duration** (`data-slot="trace-waterfall-duration"`) — Mono, tabular, width-reserved; ticks while the span runs.
- **Empty** (`data-slot="trace-waterfall-empty"`) — Rendered when there are no spans.

## Accessibility

- Role: `tree`
- A WAI-ARIA tree: each span is a treeitem with aria-level/posinset/setsize, aria-expanded for subtrees and aria-selected; one roving tab stop.
- Each treeitem is labelled “bash pnpm test, tool, 38.4s, failed” — status is spoken, never colour-only. The selected span is described by its details row.
- A polite status region announces failures and “Trace complete, 11m 52s” — ticking durations are not announced.
- The axis, grid lines, bars and now-line are decorative (aria-hidden or inside labelled items).
- Reduced motion: Bars and the now-line jump to their new positions instead of easing; the chevron turns instantly; rows and details only fade.

| Keys | Action |
| --- | --- |
| ArrowDown / ArrowUp | Moves focus to the next / previous visible span. |
| ArrowRight | Expands a collapsed span; on an expanded span moves to its first child. |
| ArrowLeft | Collapses an expanded span; otherwise moves to the parent span. |
| Home / End | First / last visible span. |
| Enter / Space | Selects the focused span (opens details); again to close. |
| Escape | Clears the selection. |

## Notes for agents

- Times are ms relative to the run start, not timestamps: convert with `span.start = +new Date(event.ts) - runStart`.
- Omit `end` (and set status running) for unfinished spans; pass `startedAt` (wall clock) or `now` so they grow.
- Put tokens/cost on leaf spans only. If every root span carries totals, the header uses the roots instead of summing.
- Ids must be unique across the whole tree; they drive selection, collapse state and focus.
- Give the root a fixed height for long traces; the axis stays sticky while the body scrolls.

## Examples

### A finished turn (minimal)

One agent span with two LLM calls and a tool call.

```tsx
import { TraceWaterfall } from "@kura-ui/react/trace-waterfall";

export function TraceWaterfallMinimal() {
  return (
    <TraceWaterfall
      className="w-full max-w-2xl"
      spans={[
        {
          id: "run",
          name: "Kura",
          kind: "agent",
          meta: "claude-opus-5-5",
          start: 0,
          end: 14_200,
          status: "done",
          children: [
            {
              id: "plan",
              name: "Plan the fix",
              kind: "llm",
              start: 0,
              end: 6_400,
              status: "done",
              tokens: { input: 12_400, output: 610 },
              cost: 0.06,
            },
            {
              id: "read",
              name: "read_file",
              kind: "tool",
              meta: "src/auth/client.ts",
              start: 6_500,
              end: 6_900,
              status: "done",
            },
            {
              id: "edit",
              name: "Write the patch",
              kind: "llm",
              start: 7_000,
              end: 14_200,
              status: "done",
              tokens: { input: 15_100, output: 1_240 },
              cost: 0.08,
            },
          ],
        },
      ]}
    />
  );
}
```

### Replay of a run (full)

The 12-minute auth-client migration replayed on a controlled clock: subagents, a failing pnpm test (selected, with its error), the fix, review and PR. The axis rescales as the run grows.

```tsx
"use client";

import { RotateCcw } from "lucide-react";
import * as React from "react";
import { IconButton } from "@kura-ui/react/icon-button";
import { type TraceSpan, TraceWaterfall } from "@kura-ui/react/trace-waterfall";

const RUN: TraceSpan = {
  id: "run",
  name: "Kura",
  kind: "agent",
  meta: "acme/web · kura/auth-client",
  start: 0,
  end: 11 * M + 52 * S,
  status: "done",
  children: [
    {
      id: "plan",
      name: "Plan the migration",
      kind: "llm",
      model: "claude-opus-5-5",
      start: 0,
      end: 9.8 * S,
      status: "done",
      tokens: { input: 18_400, output: 1_120 },
      cost: 0.11,
      input:
        "Migrate acme/web from the legacy REST session API to @acme/auth. Read the routes first.",
      output:
        "1. Read routes in src/app\n2. Map call sites of fetchUser()\n3. Patch src/auth/client.ts and src/middleware.ts\n4. Update tests, run pnpm test\n5. Open a PR",
    },
    {
      id: "routes",
      name: "read_file",
      kind: "tool",
      meta: "src/app/api/session/route.ts",
      start: 9.9 * S,
      end: 10.3 * S,
      status: "done",
      input: '{ "path": "src/app/api/session/route.ts" }',
      output: "export async function GET(req: Request) {\n  const user = await fetchUser(req)\n  …",
    },
    {
      id: "search",
      name: "search_code",
      kind: "retrieval",
      meta: "fetchUser(",
      start: 10.4 * S,
      end: 12.1 * S,
      status: "done",
      output: "14 matches in 9 files",
    },
    {
      id: "explorer",
      name: "explorer",
      kind: "agent",
      meta: "subagent",
      start: 12.5 * S,
      end: 62 * S,
      status: "done",
      children: [
        {
          id: "explorer-llm",
          name: "Find call sites",
          kind: "llm",
          model: "claude-haiku-4-5",
          start: 12.6 * S,
          end: 21 * S,
          status: "done",
          tokens: { input: 9_800, output: 420 },
          cost: 0.01,
        },
        {
          id: "explorer-grep",
          name: "bash",
          kind: "tool",
          meta: "rg -n 'fetchUser\\(' src",
          start: 21.1 * S,
          end: 21.9 * S,
          status: "done",
        },
        {
          id: "explorer-sum",
          name: "Summarize call sites",
          kind: "llm",
          model: "claude-haiku-4-5",
          start: 22.2 * S,
          end: 61.5 * S,
          status: "done",
          tokens: { input: 41_200, output: 2_300 },
          cost: 0.05,
        },
      ],
    },
    {
      id: "patch",
      name: "Draft the client patch",
      kind: "llm",
      model: "claude-opus-5-5",
      start: 63 * S,
      end: 1 * M + 40 * S,
      status: "done",
      tokens: { input: 52_300, output: 6_900 },
      cost: 0.31,
    },
    {
      id: "edit-client",
      name: "edit_file",
      kind: "tool",
      meta: "src/auth/client.ts",
      start: 1 * M + 40.2 * S,
      end: 1 * M + 40.9 * S,
      status: "done",
    },
    {
      id: "edit-mw",
      name: "edit_file",
      kind: "tool",
      meta: "src/middleware.ts",
      start: 2 * M + 8 * S,
      end: 2 * M + 8.6 * S,
      status: "done",
    },
    {
      id: "tests",
      name: "test-writer",
      kind: "agent",
      meta: "subagent",
      start: 2 * M + 12 * S,
      end: 5 * M + 28 * S,
      status: "done",
      children: [
        {
          id: "tests-llm",
          name: "Write session tests",
          kind: "llm",
          model: "claude-sonnet-4-5",
          start: 2 * M + 12 * S,
          end: 4 * M + 31 * S,
          status: "done",
          tokens: { input: 88_000, output: 9_400 },
          cost: 0.38,
        },
        {
          id: "tests-edit",
          name: "edit_file",
          kind: "tool",
          meta: "src/auth/login.test.ts",
          start: 4 * M + 32 * S,
          end: 4 * M + 33 * S,
          status: "done",
        },
      ],
    },
    {
      id: "test-1",
      name: "bash",
      kind: "tool",
      meta: "pnpm test",
      start: 5 * M + 31 * S,
      end: 6 * M + 9.4 * S,
      status: "failed",
      input: "pnpm test --filter @acme/web",
      error:
        "✕ login.test.ts › refreshes an expired session\n  Expected: 200\n  Received: 401\n\n  at src/auth/client.ts:88:11\n\nTests: 1 failed, 141 passed, 142 total",
    },
    {
      id: "diagnose",
      name: "Diagnose the failure",
      kind: "llm",
      model: "claude-opus-5-5",
      start: 6 * M + 10 * S,
      end: 7 * M + 1 * S,
      status: "done",
      tokens: { input: 71_500, output: 4_800 },
      cost: 0.29,
    },
    {
      id: "test-2",
      name: "bash",
      kind: "tool",
      meta: "pnpm test",
      start: 7 * M + 4 * S,
      end: 7 * M + 40.8 * S,
      status: "done",
      output: "Tests: 142 passed, 142 total",
    },
    {
      id: "review",
      name: "reviewer",
      kind: "agent",
      meta: "subagent",
      start: 7 * M + 42 * S,
      end: 10 * M + 48 * S,
      status: "done",
      children: [
        {
          id: "review-llm",
          name: "Review the diff",
          kind: "llm",
          model: "claude-opus-5-5",
          start: 7 * M + 42 * S,
          end: 10 * M + 48 * S,
          status: "done",
          tokens: { input: 104_000, output: 8_100 },
          cost: 0.42,
        },
      ],
    },
    {
      id: "pr",
      name: "bash",
      kind: "tool",
      meta: "gh pr create",
      start: 10 * M + 51 * S,
      end: 11 * M + 39 * S,
      status: "done",
      output: "https://github.com/acme/web/pull/482",
    },
    {
      id: "summary",
      name: "Summarize the run",
      kind: "llm",
      model: "claude-opus-5-5",
      start: 11 * M + 40 * S,
      end: 11 * M + 52 * S,
      status: "done",
      tokens: { input: 26_900, output: 4_960 },
      cost: 0.15,
    },
  ],
};

function traceAt(span: TraceSpan, t: number): TraceSpan | null {
  if (span.start > t) return null;
  const finished = span.end != null && span.end <= t;
  return {
    ...span,
    end: finished ? span.end : undefined,
    status: finished ? span.status : "running",
    output: finished ? span.output : undefined,
    error: finished ? span.error : undefined,
    tokens: finished ? span.tokens : undefined,
    cost: finished ? span.cost : undefined,
    children: span.children?.map((c) => traceAt(c, t)).filter((c): c is TraceSpan => c != null),
  };
}

const FROM = 4 * M + 40 * S;

const SPEED = 75;

const S = 1000;

const M = 60_000;

export function TraceWaterfallFull() {
  const [t, setT] = React.useState(FROM);
  const [run, setRun] = React.useState(0);
  const end = RUN.end ?? 0;

  // biome-ignore lint/correctness/useExhaustiveDependencies: `run` replays the trace
  React.useEffect(() => {
    const began = Date.now();
    setT(FROM);
    const id = setInterval(() => {
      const next = Math.min(end, FROM + (Date.now() - began) * SPEED);
      setT(next);
      if (next >= end) clearInterval(id);
    }, 120);
    return () => clearInterval(id);
  }, [run]);

  const root = traceAt(RUN, t);
  return (
    <TraceWaterfall
      className="w-full max-w-3xl"
      title="Trace"
      spans={root ? [root] : []}
      now={t}
      defaultSelectedId="test-1"
      defaultCollapsedIds={["explorer"]}
      actions={
        <IconButton
          label="Replay"
          icon={<RotateCcw />}
          variant="ghost"
          size="xs"
          className="-mr-1.5"
          onClick={() => setRun((r) => r + 1)}
        />
      }
    />
  );
}
```

### Live, from a wall clock (state)

A subagent that is still running: `startedAt` makes running bars grow in real time.

```tsx
"use client";

import * as React from "react";
import { TraceWaterfall } from "@kura-ui/react/trace-waterfall";

export function TraceWaterfallLive() {
  const [startedAt] = React.useState(() => Date.now() - 38_000);
  return (
    <TraceWaterfall
      className="w-full max-w-2xl"
      title="test-writer"
      startedAt={startedAt}
      spans={[
        {
          id: "tw",
          name: "test-writer",
          kind: "agent",
          meta: "subagent",
          start: 0,
          status: "running",
          children: [
            {
              id: "tw-read",
              name: "read_file",
              kind: "tool",
              meta: "src/auth/login.test.ts",
              start: 400,
              end: 900,
              status: "done",
            },
            {
              id: "tw-ctx",
              name: "search_code",
              kind: "retrieval",
              meta: "refreshSession",
              start: 1_000,
              end: 2_600,
              status: "done",
            },
            {
              id: "tw-llm",
              name: "Write session tests",
              kind: "llm",
              start: 2_800,
              end: 24_100,
              status: "done",
              tokens: { input: 31_200, output: 2_870 },
              cost: 0.14,
            },
            {
              id: "tw-approve",
              name: "edit_file",
              kind: "tool",
              meta: "src/auth/session.test.ts",
              start: 24_300,
              end: 25_000,
              status: "done",
            },
            {
              id: "tw-run",
              name: "bash",
              kind: "tool",
              meta: "pnpm vitest session",
              start: 25_200,
              status: "running",
            },
          ],
        },
      ]}
    />
  );
}
```

### Custom details (composition)

`renderDetails` shows the edit a tool made as a CodeBlock.

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

export function TraceWaterfallCustomDetails() {
  return (
    <TraceWaterfall
      className="w-full max-w-2xl"
      title="Tool calls"
      defaultSelectedId="edit"
      spans={[
        {
          id: "turn",
          name: "Fix token refresh",
          kind: "agent",
          start: 0,
          end: 9_300,
          status: "done",
          children: [
            {
              id: "think",
              name: "Diagnose the failure",
              kind: "llm",
              start: 0,
              end: 7_900,
              status: "done",
              tokens: { input: 71_500, output: 4_800 },
              cost: 0.29,
            },
            {
              id: "edit",
              name: "edit_file",
              kind: "tool",
              meta: "src/auth/client.ts",
              start: 8_000,
              end: 8_400,
              status: "done",
            },
            {
              id: "test",
              name: "bash",
              kind: "tool",
              meta: "pnpm test login",
              start: 8_500,
              end: 9_300,
              status: "done",
            },
          ],
        },
      ]}
      renderDetails={(span) =>
        span.id === "edit" ? (
          <CodeBlock
            language="ts"
            filename="src/auth/client.ts"
            code={`if (res.status === 401 && session.refreshToken) {\n  session = await auth.refresh(session.refreshToken)\n  return retry(req, session)\n}`}
          />
        ) : null
      }
    />
  );
}
```

## Dependencies

- npm: `lucide-react`
- Kura registry items: `kura-theme`, `kura-format`, `status-glyph`, `use-controllable-state`, `use-elapsed`, `utils`
- Related: `task-list`, `agent-fleet`, `run-header`, `tool-call`, `agent-timeline`

---

# 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 blue accent 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 />
```

### useElapsed

Live elapsed time since a start instant while something is running, frozen when it stops. SSR-safe (null until mounted).

```ts
import { useElapsed } from "@kura-ui/react/hooks";
useElapsed(since: Date | number | null | undefined, running: boolean, interval?: number): number | null
```

Returns: Milliseconds since `since`, or null before mount or without a start time.


```tsx
const ms = useElapsed(run.startedAt, run.status === "running");
<span>{ms == null ? "—" : formatClock(ms)}</span>
```

---

# 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 (blue
   "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 — true greys (no tint), Geist-like steps

| Step      | Use                       | Light              | Dark               |
| --------- | ------------------------- | ------------------ | ------------------ |
| `gray-1`  | app canvas                | `oklch(0.99 0 0)`  | `oklch(0.145 0 0)` |
| `gray-2`  | subtle / sunken bg        | `oklch(0.975 0 0)` | `oklch(0.17 0 0)`  |
| `gray-3`  | UI element bg             | `oklch(0.96 0 0)`  | `oklch(0.2 0 0)`   |
| `gray-4`  | hovered element bg        | `oklch(0.94 0 0)`  | `oklch(0.225 0 0)` |
| `gray-5`  | active element bg         | `oklch(0.92 0 0)`  | `oklch(0.25 0 0)`  |
| `gray-6`  | subtle borders            | `oklch(0.895 0 0)` | `oklch(0.28 0 0)`  |
| `gray-7`  | borders                   | `oklch(0.86 0 0)`  | `oklch(0.33 0 0)`  |
| `gray-8`  | strong borders            | `oklch(0.79 0 0)`  | `oklch(0.41 0 0)`  |
| `gray-9`  | solid                     | `oklch(0.64 0 0)`  | `oklch(0.55 0 0)`  |
| `gray-10` | placeholder / subtle text | `oklch(0.58 0 0)`  | `oklch(0.62 0 0)`  |
| `gray-11` | muted text (≥ 4.5:1)      | `oklch(0.46 0 0)`  | `oklch(0.74 0 0)`  |
| `gray-12` | primary text, ink         | `oklch(0.16 0 0)`  | `oklch(0.97 0 0)`  |

Cards are white on a near-white canvas in light, and one step lighter than a near-black canvas in dark.

### 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" (blue, hue ~260)

Light `oklch(0.56 0.2 260)`, dark `oklch(0.68 0.17 258)`. 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).
- No ornaments: no textures, glows, glassmorphism on chrome, serif/italic display type or brush marks.
  Taste comes from typography, spacing, contrast and motion, not decoration.

---

## 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.

{agent?.name}

Migrate to the new auth client

Fix flaky date test