` with a real heading, so it fits your page outline. - Every state is in words. The over-budget warning is a sentence, not a colour. - The budget bar is decorative and hidden; its label carries the same information. - Nothing animates, so there is nothing to pause. ## When not to use - **During a run.** Live spend belongs to a meter beside the run, not to this. - **On a billing page.** This is a decision surface, not an invoice. - **For token counts.** Tokens aren't a unit people can judge. Convert to money, credits or time first. ## Why it works this way The API refuses the two lies this surface usually tells. First, a single figure: `cost` is a range, and a caller who genuinely knows the price passes only `low`, which makes precision an explicit choice rather than the default. Second, a percentage of certainty: confidence reuses the shipped three-tier Confidence Meter instead of inventing a number, and `basis` names the evidence so the estimate can be judged. Everything arrives pre-formatted as strings because currency, locale and credit units belong to the host product; a component that formatted money would have to guess a currency and would be wrong in half the places it renders. The only proportion drawn is the budget bar, which comes from a measured `used` value — the same rule the rest of the system applies to progress. `exceeds` is a separate flag rather than something derived from the numbers, because only the caller knows whether the estimate's high end, the low end, or an average is the figure that counts against a budget. --- Follow the PixelDosa UI rules when building with this component: https://pixeldosa.akshayjayan.com/llms.txt --- # Credits Meter > What's left, and what this action will cost — named together, before the click. ```bash npx shadcn@latest add @pixeldosa/credits-meter ``` **Before you use it:** Requires `cn` at `@/lib/utils`. Keep `nextAction.label` specific to the click it sits beside: '8 images · 1024 × 1024', not 'Generate'. ## Usage ```tsx import { CreditsMeter } from "@/components/ui/credits-meter"; ``` ## Why it exists Credit opacity is the first frustration buyers name in reviews of these tools. The specific complaint isn't the price, it's that you can't tell what an action will cost until it's already gone — and refunds, when they happen, are invisible. ## Features - **The action and its price are one object**, so they can never be rendered apart. - **"More than you have"** is stated when the next action exceeds the balance, before the click. - **Refunds have somewhere to appear.** Pipelines refund routinely; interfaces rarely say so. - **Expiry in plain words:** "Resets on 1 October". - **Measured only.** The bar is drawn from a real `used` value, never an estimate. - **The bar empties as the balance falls.** You pass what's been spent; it draws what's left, so the graphic and the figure above it never say opposite things. ## Variants ### Enough left ### Not enough for this action ## Props | Prop | Type | Notes | | --- | --- | --- | | `remaining` | `string` | Required, formatted by you. | | `allowance` | `string` | The full allowance, when there is one. | | `used` | `number` | Measured, 0–1, the share already spent. The bar draws the remainder. | | `nextAction` | `{ label, cost, affordable? }` | The click this sits beside, and its price. | | `resets` | `string` | When the balance renews or expires. | | `recent` | `string` | Recent movement, including refunds. | | `low` | `boolean` | Marks a balance worth flagging. | | `onTopUp` / `topUpLabel` | `() => void` / `string` | | | `label` | `string` | Defaults to `"Credits"`. | ## Accessibility - A labelled group; every figure is text, and the bar is decorative. - "More than you have" is a sentence, not only a colour. ## When not to use - **A billing page.** This is a decision aid beside an action. - **Raw token counts.** Convert to the unit people are charged in. - **A whole run's estimate** before it starts: use `Cost Estimate`. ## Why it works this way `nextAction` is a single object rather than separate label and cost props so the two can never be rendered apart: a price with no action, or an action with no price, is the pattern the component exists to replace. `affordable` is a caller flag instead of something derived from parsing the strings, because balances and costs arrive as formatted text in whatever unit and locale the product uses, and a component that tried to compare them would have to parse money. The bar is drawn only from a measured `used` value, which keeps it consistent with the rest of the system's rule that a proportion must be real, and it draws what is *left* rather than what is spent: it sits under a figure that counts down, and a bar filling up beside a balance running out reads as plenty-left at the exact moment it is not. Refunds get a place in `recent` because generation pipelines refund routinely and almost no interface shows it, which leaves people believing failures cost them money. --- Follow the PixelDosa UI rules when building with this component: https://pixeldosa.akshayjayan.com/llms.txt --- # Diff Accept > Review an AI-proposed text change as an inline diff, resolved hunk by hunk — not all-or-nothing — with a conflict guard if the base text has drifted. ```bash npx shadcn@latest add @pixeldosa/diff-accept ``` **Before you use it:** Uses diffWords from the diff package for word-level diffing — not a line-level diff, since this targets prose fields, not code. Unlike smart-field/ghost-input, this component does not call an AI provider itself; the consumer supplies an already-generated proposedValue (which may itself come from a smart-field-style fetch). baseValue must be exactly the text the proposal was generated against, not the current value, or the conflict guard will trigger on every render. ## Usage ```tsx "use client"; import * as React from "react"; import { DiffAccept } from "@/components/ui/diff-accept"; export function BioField() { const [value, setValue] = React.useState(bio); const [proposal, setProposal] = React.useState<{ base: string; proposed: string } | null>(null); async function rewrite() { const proposed = await callYourModel(value); setProposal({ base: value, proposed }); } return ( <>

setValue(e.target.value)} />
      <button onClick={rewrite}>Rewrite with AI</button>
      {proposal ? (
        <DiffAccept
          baseValue={proposal.base}
          value={value}
          proposedValue={proposal.proposed}
          onApply={(merged) => setValue(merged)}
          onRegenerate={rewrite}
        />
      ) : null}
    </>
  );
}
```

Unlike `Smart Field` or `Ghost Input`, this component doesn't call an AI provider
itself — it takes an already-generated `proposedValue` (which may come from your own
call, or a `Smart Field`-style `fetchProposal`) and handles reviewing it.

### Per-hunk review, not all-or-nothing

Each changed region renders inline with its own Accept/Reject controls. Unresolved
hunks default to the **original** text when you click Apply — a change only lands in
the result if it was explicitly accepted.

### Conflict guard

`baseValue` must be exactly the text the proposal was generated against. If `value`
(the current live value) no longer matches it — the user edited the text elsewhere
while the proposal was in flight — the diff is not shown. A conflict banner explains
why and offers `onRegenerate` instead of risking a stale merge.

## Features

- **Hunk-by-hunk review, not all-or-nothing** — each changed region has its own
  Accept/Reject, and unresolved hunks fall back to the *original* text on Apply. A
  change only lands if it was explicitly accepted.
- **A conflict guard that refuses to guess.** If the live `value` has drifted from the
  `baseValue` the proposal was generated against, the diff is withheld entirely and
  the user is offered a regenerate instead of a stale merge.
- **Decoration, not colour**, for additions and removals — strikethrough and underline
  read correctly for colourblind users, and the token set has no red/green pair to
  spend here anyway (DESIGN.md §3.2).
- **A real undo window** after Apply, so accepting is recoverable rather than final.
- **Labels that survive being read out of context**: each control names the actual
  changed text, e.g. `Accept: "design engineer"`, not a bare "Accept".
- **Provider-agnostic** — it reviews a `proposedValue` you already have, and never
  calls a model itself.

## Examples

Composed after a `Smart Field`-style proposal, where the model call lives in your code
and this component only handles the review step:

```tsx
const [proposal, setProposal] = React.useState<{ base: string; proposed: string } | null>(null);

async function rewrite() {
  const base = value;
  setProposal({ base, proposed: await callYourModel(base) });
}

{proposal ? (
  <DiffAccept
    baseValue={proposal.base}
    value={value}
    proposedValue={proposal.proposed}
    onApply={(merged) => {
      setValue(merged);
      setProposal(null);
    }}
    onRegenerate={rewrite}
  />
) : null}
```

Lengthening the undo window for a higher-stakes field, where a mistaken Apply is
costlier to notice late:

```tsx
<DiffAccept
  baseValue={base}
  value={value}
  proposedValue={proposed}
  onApply={setValue}
  undoWindowMs={15000}
/>
```

Omitting `onRegenerate` is valid — the conflict banner then explains the drift without
offering a retry, which is the right call when regenerating would cost a paid call the
user didn't ask for.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `baseValue` | `string` | — | Required. The text the proposal was generated against. |
| `value` | `string` | — | Required. The current live value, compared to `baseValue` for conflicts. |
| `proposedValue` | `string` | — | Required. The AI's proposed replacement text. |
| `onApply` | `(mergedValue: string) => void` | — | Required. Fires with the resolved merge when Apply is clicked. |
| `onRegenerate` | `() => void` | — | Shown as a button on conflict. |
| `undoWindowMs` | `number` | `6000` | How long Undo stays available after Apply. |

## Accessibility

- Each hunk's Accept/Reject buttons carry a label naming the actual changed text
  (e.g. `Accept: "design engineer"`), not just "Accept" — meaningful out of context.
- Additions and removals are distinguished by text decoration (strikethrough /
  underline + tint), not colour alone — the token set has no red/green pair to spend
  on this anyway, and decoration reads correctly for colourblind users.
- Apply/Undo state changes are announced via `aria-live="polite"`.
- Every control is a real, keyboard-reachable `<button>`.
- Under `prefers-reduced-motion`, all colour/background transitions drop to instant
  state changes; the underlying decoration stays fully legible without animation.

## When not to use

A single atomic value with no internal structure to partially accept — a company name,
a date, a category — is `Smart Field`, not this. Diff Accept is for text with multiple
independently-reviewable regions.

## Why it works this way

Uses diff (jsdiff) for the actual word-level diff computation rather than hand-rolling a diff algorithm — the same relationship command-menu has with cmdk: a solved problem with real edge cases (Unicode, whitespace runs, word-boundary detection) not worth re-solving here. Hunks are grouped from the raw diff parts by merging consecutive added/removed runs into one reviewable unit, so a 'replace X with Y' shows as a single hunk with both the removal and the replacement, not two separate uncoordinated changes. Unresolved (pending) hunks default to the original text when merging, never the proposed one — an AI change only lands in the final result if a hunk is explicitly accepted, matching the system-wide 'never silently commit' rule. The status model is a three-state machine (reviewing/applied/done) rather than a single boolean: collapsing 'applied' and 'done' into one flag caused a real bug during development, where the conflict check (value !== baseValue, which becomes true immediately after Apply changes the live value) would incorrectly override the Undo affordance and show a conflict banner instead — the fix was ordering status checks so 'applied'/'done' short-circuit before the conflict check ever runs, since conflict is only a meaningful question while still reviewing.

---

Follow the PixelDosa UI rules when building with this component: https://pixeldosa.akshayjayan.com/llms.txt

---

# Draft Mode

> The agent prepares everything and nothing leaves until a person sends it.

```bash
npx shadcn@latest add @pixeldosa/draft-mode
```

**Before you use it:** Requires `cn` at `@/lib/utils`. The component owns only the selection; the held items, the mode and what sending means stay with you.

## Usage

```tsx
"use client";

import { DraftMode } from "@/components/ui/draft-mode";

<DraftMode
  enabled={draftMode}
  onEnabledChange={setDraftMode}
  items={held}
  onSend={send}
  onDiscard={discard}
  onEdit={open}
/>
```

## Why it exists

An approval dialog interrupts once per action, which teaches people to click through it.
Draft mode is the opposite: the agent works freely, its output collects in one place, and
the person reviews a batch when they choose to. Same protection, far less interruption.

## Features

- **Nothing sends itself.** Items are chosen with checkboxes, and the button names the
  count: "Send 3".
- **Irreversible work is marked** on the item, and counted in the sentence under the
  button as the selection changes.
- **"Select all" is a visible step**, never a hidden accept-all.
- **Off is explained, not silent.** With draft mode off, a still, orange-marked strip says
  what happens instead and offers to turn it back on.
- **Stale selections can't fire.** An item that leaves the list is dropped from the
  selection, so a batch action can't send something that has already gone.
- **Holds completely still.** Everything here is your turn.

## Variants

### Waiting for review

### Nothing waiting

### Draft mode off

## Props

| Prop | Type | Notes |
| --- | --- | --- |
| `enabled` | `boolean` | Required. |
| `onEnabledChange` | `(enabled: boolean) => void` | Required. |
| `items` | `{ id, title, target?, detail?, irreversible? }[]` | Required. Phrase `title` as the consequence. |
| `onSend` | `(ids: string[]) => void` | Required. |
| `onDiscard` | `(ids: string[]) => void` | Adds a Discard action. |
| `onEdit` | `(id: string) => void` | Adds Edit on each item. |
| `offWarning` | `string` | What happens with the mode off, in your product's words. |
| `emptyLabel` | `string` | Shown when nothing is waiting. |
| `title` | `string` | Defaults to `"Draft mode"`. |
| `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | Defaults to `3`. |

## Accessibility

- A labelled `<section>`; the mode control is a real `role="switch"` with its state in
  words as well as position.
- Each item is a checkbox with a full label, so the whole row is a hit target.
- Sends and discards are announced through a polite live region, with the count.
- "Can't be undone" is text, not only a colour.

## When not to use

- **One high-risk action awaiting a decision** is `AI Approval Gate`, which states the
  consequence and takes the decision on its own.
- **Many AI-proposed edits to review row by row** is `AI Triage Table`.
- **Choosing how much the agent may do without asking** is `Autonomy Control`. Draft mode
  is about what leaves, not about what the agent may attempt.

## Why it works this way

Selection is the component's only state, and it is pruned against `items` on every change: an id that has left the list is dropped, because a stale id surviving in the selection is exactly how a batch action sends the wrong thing. There is no accept-all shortcut hiding behind a single control — 'Select all' is a visible, reversible selection step before the send, and the send button carries the count so the action names its own size. Irreversibility is counted from the chosen items rather than shown per row only, so the sentence under the button changes as the selection changes and the warning cannot be scrolled past. The mode switch is a real `role="switch"` with an explanatory sentence that rewrites itself for each state, instead of a settings label that leaves people guessing what 'off' does; turning it off does not hide the consequence, it states it in the waiting colour and offers the way back.

---

Follow the PixelDosa UI rules when building with this component: https://pixeldosa.akshayjayan.com/llms.txt

---

# Field

> A composable form-field wrapper — Field, FieldLabel, FieldControl, FieldDescription and FieldError — that wires ARIA automatically onto whatever control you place inside it.

```bash
npx shadcn@latest add @pixeldosa/field
```

**Before you use it:** FieldControl clones its single child rather than rendering a wrapper element, so pass exactly one React element (an <input>, <textarea>, or a component that forwards id/aria-invalid/aria-describedby/ref to a real form control) as its child.

## Usage

```tsx
import { Field, FieldControl, FieldDescription, FieldError, FieldLabel } from "@/components/ui/field";

export function EmailField({ value, onChange, error }: Props) {
  return (
    <Field invalid={Boolean(error)}>
      <FieldLabel>Email</FieldLabel>
      <FieldControl>
        <input type="email" value={value} onChange={onChange} className="…" />
      </FieldControl>
      <FieldDescription>We'll only use this to send order updates.</FieldDescription>
      <FieldError>{error}</FieldError>
    </Field>
  );
}
```

`FieldControl` clones its single child, so it accepts exactly one React element — a
native `<input>`/`<textarea>`, or any component that forwards `id`, `aria-invalid`,
`aria-describedby` and `ref` to a real form control.

`FieldError` renders nothing when its children are falsy, so you can pass a validation
message straight through without a conditional wrapper.

## Features

- **ARIA wiring you never write by hand**: the control receives `id`,
  `aria-invalid` and a composed `aria-describedby` pointing at whichever of the
  description and error are actually present.
- **Bring your own control** — `FieldControl` clones its single child, so it works
  with a native `<input>`/`<textarea>` or any component that forwards `id`, `ref`
  and the ARIA attributes to a real form control.
- **`FieldError` renders nothing when falsy**, so a validation message can be passed
  straight through without a conditional wrapper around it.
- **Announced late errors**: `role="alert"` means an async validation message is read
  out even when the field already has focus.

## Variants

The default state — label, control, and a supporting description.

<Field className="w-full max-w-sm">
    <FieldLabel>Email</FieldLabel>
    <FieldControl>
      <input
        type="email"
        defaultValue="hello@pixeldosa.dev"
        className="h-9 w-full rounded-md border border-input bg-transparent px-3 text-sm"
      />
    </FieldControl>
    <FieldDescription>We'll only use this to send order updates.</FieldDescription>
  </Field>

### Invalid

`invalid` flows into `aria-invalid` on the control, which the input styling hooks with
`aria-invalid:` variants — the ring is a consequence of the ARIA state, not a parallel
visual flag that can drift out of sync with it.

<Field invalid className="w-full max-w-sm">
    <FieldLabel>Email</FieldLabel>
    <FieldControl>
      <input
        type="email"
        defaultValue="hello@"
        aria-invalid
        className="h-9 w-full rounded-md border border-input bg-transparent px-3 text-sm aria-invalid:border-destructive"
      />
    </FieldControl>
    <FieldError>Enter a complete email address.</FieldError>
  </Field>

## Props

### Field

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` | generated | Base id for the control. Descendants derive `-description` and `-error` ids from it. |
| `invalid` | `boolean` | `false` | Marks the field invalid — flows into `aria-invalid` on the control. |

### FieldControl

Takes exactly one child element. No other props.

### FieldLabel, FieldDescription, FieldError

Standard `label` / `p` / `p` props. Must be rendered inside a `Field`.

## Accessibility

- The control receives `aria-describedby` combining the error and description ids
  automatically — you never write that string by hand.
- `FieldError` uses `role="alert"` so a message appearing after the field already has
  focus (e.g. from async validation) is still announced.
- `aria-invalid` is set on the control whenever `Field`'s `invalid` prop is true, which
  most input styling (including this system's) hooks with `aria-invalid:` variants.

## Why it works this way

Built as a compound-component set sharing React context rather than a single Field component with many props, because form fields have a genuinely variable shape (some have descriptions, some don't; some controls are custom comboboxes, not <input>) and a large prop-driven API would force every consumer through the same limited combinations. FieldControl clones its child instead of rendering its own DOM node specifically so that input+icon or input+button compositions keep their existing layout — a wrapper div would break those. FieldDescription and FieldError register their presence into context via an effect so FieldControl's aria-describedby is always accurate even when a description or error mounts after the control, which happens constantly with async validation.

---

Follow the PixelDosa UI rules when building with this component: https://pixeldosa.akshayjayan.com/llms.txt

---

# Generation Job

> A generation that takes minutes — queue position, honest waits, partial results and refunds.

```bash
npx shadcn@latest add @pixeldosa/generation-job
```

**Before you use it:** Requires `cn` at `@/lib/utils`. Pass `progress` only when you measure it; the component deliberately draws nothing otherwise.

## Usage

```tsx
"use client";

import { GenerationJob } from "@/components/ui/generation-job";

<GenerationJob
  status={job.status}
  title="4 product images · 1024 × 1024"
  queue={{ position: job.queuePosition, typicalWait: "2 to 4 minutes" }}
  stage={job.stage}
  progress={job.measuredProgress}
  startedAt={job.startedAt}
  cost="40 credits"
  refundNote="Anything that fails is refunded"
  onCancel={job.cancel}
>
  {job.outputs.map((output) => <img key={output.id} src={output.url} alt="" />)}
</GenerationJob>
```

Pass `progress` only when you measure it. Without it, no bar is drawn.

## Why it exists

Reviews of image and video tools rank credits and unexplained waiting above quality.
Queues of ten to thirty minutes are normal at peak, and people are given a spinner, no
position, no estimate, and no idea what happens to their credits when a job fails.

## Features

- **The queue is a real state:** position, plus what the wait usually is at this moment.
- **No invented progress.** A bar appears only when you pass a measured `progress`.
- **Partial results show immediately.** With `status="partial"`, two finished images of
  four are two finished images, not a spinner.
- **The refund rule is stated before a failure**, and what happened to the money after
  one.
- **Nobody has to watch.** A "Tell me when it's done" checkbox, so long jobs don't hold
  someone at the screen.
- **Stop stays visible** for the whole run, and the elapsed counter ticks itself.

## Variants

### In the queue

### Failed, with the credits back

## Props

| Prop | Type | Notes |
| --- | --- | --- |
| `status` | `"queued" \| "running" \| "partial" \| "done" \| "failed" \| "cancelled"` | Required. |
| `title` | `string` | Required. What's being made. |
| `queue` | `{ position?, typicalWait? }` | Say what you know. |
| `stage` | `string` | "Rendering 3 of 4". Shimmers while running. |
| `progress` | `number` | Measured, 0–1. Omit and no bar is drawn. |
| `startedAt` | `number \| Date` | Drives the elapsed counter. |
| `cost` / `refundNote` | `string` | Formatted by you. |
| `error` | `{ message, refunded? }` | The reason, and what happened to the money. |
| `notify` / `onNotifyChange` | `boolean` / `(v) => void` | "Tell me when it's done". |
| `onCancel` / `onRetry` | `() => void` | Stop while active; Try again after a failure. |
| `children` | `ReactNode` | Finished outputs, shown as they land. |

## Accessibility

- A labelled `<section>` with a real heading.
- Status, queue position and failures are announced once through a polite live region —
  the ticking counter is not announced.
- The progress bar is decorative; the words carry the same information.
- The status dot's pulse stops under `prefers-reduced-motion`.

## When not to use

- **Work that takes a second or two:** use `Generation Placeholder`.
- **An agent run with steps:** use `Agent Plan` with statuses.
- **A list of past jobs:** this is one job. A queue of many is a different surface.

## Why it works this way

Built against the complaints this category actually generates: reviews of image and video tools rank credits and unexplained waits above quality, and queue times of ten to thirty minutes at peak are normal. So the queue is a first-class state with a position and a typical wait rather than a spinner; `progress` is optional and a bar is drawn only when it is passed, because an invented bar on a job whose extent is unknown is the same lie as fake typing; `partial` exists as a status so a batch with two of four finished can show two, which the pipeline literature treats as the correct outcome rather than a pass or fail; and `error` carries a refund string beside the reason, because a failure that silently keeps someone's credits is the complaint underneath most one-star reviews. The elapsed counter ticks inside the component — the one place this system breaks its caller-owns-async rule — so a minutes-long job doesn't force a re-render a second on the consumer.

---

Follow the PixelDosa UI rules when building with this component: https://pixeldosa.akshayjayan.com/llms.txt

---

# Generation Placeholder

> A layout-reserving placeholder for AI-generated media that encodes real generation progress as a resolving dot field, then cross-fades into the finished artifact.

```bash
npx shadcn@latest add @pixeldosa/generation-placeholder
```

**Before you use it:** Requires `cn` at `@/lib/utils` and the `pd-fade-in` keyframe supplied by @pixeldosa/pixeldosa-theme's css block. `aspectRatio` is deliberately required rather than optional — it is the prop that prevents a layout shift when the artifact arrives, which is the whole reason this is a container component.

## Usage

```tsx
"use client";

import { GenerationPlaceholder } from "@/components/ui/generation-placeholder";

export function GeneratedImage({ job }: { job: Job }) {
  return (
    <GenerationPlaceholder
      status={job.status}
      progress={job.step / job.totalSteps}
      aspectRatio="16 / 9"
      label="Generating image"
      onCancel={() => job.abort()}
    >
      <img src={job.url} alt={job.prompt} />
    </GenerationPlaceholder>
  );
}
```

The component is a **container**, not a sibling that gets swapped out — children render
only once `status` is `done`. That, plus the required `aspectRatio`, is what keeps the
layout still at the exact moment the artifact appears.

## Features

- **Progress is spatial, not temporal.** Every cell holds a stable pseudo-random
  threshold and resolves once `progress` passes it — ordered-dither logic borrowed from
  halftone rendering. The pattern *is* the information, so it stays readable with every
  animation removed.
- **Never a fabricated percentage.** `progress` is optional with no synthetic fallback.
  Omit it and you get an honest indeterminate wave rather than a number creeping toward
  90%. A percentage appears only when your backend actually measured one.
- **`aspectRatio` is required, deliberately.** A media placeholder that resizes when the
  artifact arrives causes a layout shift precisely where the user is looking.
- **`processing` is its own state.** Upscaling and encoding are neither generating nor
  done, so a user is never told "done" while work is still running.
- **Four forms, one threshold engine.** `field` (dot density), `mosaic` (coarse→fine
  resolution — the closest to what generation actually does), `sweep` (a soft develop
  frontier), and `bars` for audio, where a rectangle would misrepresent the medium.
- **Cancel stays visible** through every active state, never hidden behind a hover.
- **Failure stops visibly.** It takes the whole surface with an icon, a plain-language
  cause, and a retry — rather than dimming the field and reddening a caption, which
  reads as "still working, but sad".
- **The indeterminate wave is a CSS animation**, not a frame loop. Hundreds of cells
  animate on the compositor with a per-cell delay; React never re-renders.

## Variants

A measured generation at 41% — the frontier reads as a soft edge because each cell
crosses its own threshold rather than a shared one.

### Queued

Accepted, not started. Sparse and at rest, so "waiting in line" doesn't read as
"working".

### Indeterminate

No `progress` supplied — a travelling wave rather than an invented number. This is the
honest default when the backend doesn't report steps.

### Mosaic

Blocks subdivide coarse → fine as progress climbs. This is what an image actually does
while it generates — it gains *resolution*, not area — which is why it communicates
"nearly there" more honestly than a bar. Resolution steps in doublings rather than
easing, because a smoothly shrinking block reads as a zoom instead of a refinement.

### Sweep

A develop frontier with a soft gradient edge — the closest of the four to the gradient
wash people recognise from Gemini-style generation. The frontier sits exactly at
`progress`, so the visual and the number can never disagree.

### Audio

`form="bars"` for a medium that isn't a rectangle. Same threshold engine, different
geometry.

### Failed

Failure takes the whole surface rather than dimming the field and turning a caption
red — a stopped state should visibly stop. The field stays faintly behind it, showing
how far it got, and `onRetry` gives the message somewhere to go.

## Examples

Driving it from a real job. Note that `progress` is passed **only** while generating —
during `processing` there is nothing measured to report, so it's omitted rather than
frozen at 100%:

```tsx
<GenerationPlaceholder
  status={job.status}
  progress={job.status === "generating" ? job.step / job.totalSteps : undefined}
  aspectRatio="1 / 1"
  label={job.status === "processing" ? "Upscaling" : "Generating image"}
  onCancel={job.abort}
>
  <img src={job.url} alt={job.prompt} />
</GenerationPlaceholder>
```

A grid of variations, each with its own job — `density="sm"` keeps the field legible at
a small size:

```tsx
<div className="grid grid-cols-4 gap-3">
  {jobs.map((job) => (
    <GenerationPlaceholder
      key={job.id}
      status={job.status}
      progress={job.progress}
      aspectRatio="1 / 1"
      density="sm"
      label={`Variation ${job.index}`}
    >
      <img src={job.url} alt="" />
    </GenerationPlaceholder>
  ))}
</div>
```

Video, where the measurable quantity is encoded frames rather than diffusion steps:

```tsx
<GenerationPlaceholder
  status="processing"
  aspectRatio="16 / 9"
  label={`Encoding · frame ${frame} of ${total}`}
>
  <video src={url} controls />
</GenerationPlaceholder>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `status` | `"queued" \| "generating" \| "processing" \| "done" \| "failed"` | — | Required. |
| `progress` | `number` | — | 0–1. Only supply it when it was actually measured; omit for indeterminate. |
| `aspectRatio` | `string` | — | Required. Reserves the artifact's final bounds, e.g. `"16 / 9"`. |
| `label` | `string` | — | Required. Both the visible and the announced status text. |
| `form` | `"field" \| "mosaic" \| "sweep" \| "bars"` | `"field"` | `field` dot density, `mosaic` coarse→fine resolution, `sweep` a soft develop frontier, `bars` for audio. |
| `density` | `"sm" \| "default" \| "lg"` | `"default"` | Cell count. `sm` for grid cells, `lg` for hero surfaces. |
| `onCancel` | `() => void` | — | Shown during `generating` and `processing`. |
| `onRetry` | `() => void` | — | Recovery action on `failed`. Without it the failure explains but can't be acted on. |
| `children` | `ReactNode` | — | The artifact. Rendered only when `status` is `done`. |

All other props forward to the wrapping `<div>`.

## Accessibility

- The dot field is `aria-hidden` — supplementary, never the only signal. The `label`
  plus the percentage is the real status, in an `aria-live="polite"` region.
- The percentage uses `tabular-nums`, so the line doesn't shift as it climbs.
- Cancel is a real keyboard-reachable `<button>` with a hit area extended to ~44px
  while its visible size stays compact.
- Under `prefers-reduced-motion` every transition is dropped and the indeterminate loop
  never starts. Cells hold a static pattern — and because progress was already encoded
  spatially, **nothing is lost**. This is the rare case where the reduced-motion state
  carries exactly the same information as the animated one.

## When not to use

Streaming text is `Progressive Reveal` — it appends whole items, where this refines in
place. Agent activity with no artifact attached is `Agent Presence` (planned). And this
is not a generic content skeleton: it exists precisely because media generation
progress is *measurable*, and a skeleton throws that information away.

## Why it works this way

The load-bearing decision is that progress is encoded spatially, not temporally. Each cell derives a stable pseudo-random threshold from its index (a deterministic sine hash, so the pattern never reshuffles between renders — a reshuffling field reads as noise rather than a resolve), and a cell resolves once `progress` passes its threshold. That is ordered-dither logic borrowed from halftone rendering: it produces an organic dissolve that is nonetheless an exact function of real progress, rather than a decorative animation that merely implies work. The payoff is the reduced-motion story, which is unusually strong for an animated component: because the information lives in the pattern rather than the movement, `prefers-reduced-motion` removes every transition and the progress stays completely legible — no fallback had to be invented. `progress` is optional with no synthetic fallback, deliberately: media generation genuinely reports steps (diffusion iterations, encoded frames) where text streaming does not, so a percentage here is measured rather than invented — the system's rule is not 'never show a number' but 'never invent precision you don't have', which is the same rule that makes Confidence Meter refuse one. `aspectRatio` is required because a media placeholder that resizes on completion causes a layout shift at exactly the moment the user's attention is on it. `processing` exists as a state separate from `generating` so a user is never told 'done' while an upscale or encode is still running. The requestAnimationFrame loop that drives indeterminate mode is not started at all when the component is determinate or motion is reduced, since an animation frame loop nobody can see is pure battery cost.

---

Follow the PixelDosa UI rules when building with this component: https://pixeldosa.akshayjayan.com/llms.txt

---

# Ghost Input

> A single-line input with inline AI ghost-text completion — pause, see a dimmed continuation, accept with Tab or dismiss with Escape.

```bash
npx shadcn@latest add @pixeldosa/ghost-input
```

Composes (installed automatically): `field`.

**Before you use it:** value/onValueChange are required — this is a controlled component only. fetchSuggestion must resolve to the FULL continued string (current value + completion), not just the completion tail; the component slices the tail itself and drops any result that doesn't start with the value it was requested for, so a response arriving after the user has kept typing can't overwrite what they see. Drops into <FieldControl> directly since id/aria-invalid/aria-describedby/ref all forward to the underlying <input>.

## Usage

```tsx
import { GhostInput } from "@/components/ui/ghost-input";

async function fetchSuggestion(value: string, signal: AbortSignal) {
  const res = await fetch("/api/complete", {
    method: "POST",
    body: JSON.stringify({ prompt: value }),
    signal,
  });
  const { completion } = await res.json();
  // Must return the FULL string — current value plus the completion.
  return value + completion;
}

export function ReplyBox() {
  const [value, setValue] = useState("");

return (
    <GhostInput
      value={value}
      onValueChange={setValue}
      fetchSuggestion={fetchSuggestion}
      placeholder="Write a reply…"
    />
  );
}
```

Inside a `Field`, drop it straight into `FieldControl` — id and ARIA wiring pass through:

```tsx
<Field>
  <FieldLabel>Reply</FieldLabel>
  <FieldControl>
    <GhostInput value={value} onValueChange={setValue} fetchSuggestion={fetchSuggestion} />
  </FieldControl>
</Field>
```

## Features

- **Race-proof suggestions**: every keystroke aborts the in-flight request before
  starting a new debounce, and any response that doesn't extend the current value is
  discarded — a slow reply can never overwrite what the user is now looking at.
- **Nothing is ever inserted for you.** Tab (or → at the end of the text) accepts, Esc
  dismisses. There is no auto-accept timer, by design.
- **A real `<input>`, not a contentEditable** — IME composition, autofill, native undo
  and screen-reader field semantics all behave exactly as they would in a plain input.
- **Announced without double-reading**: the ghost text is `aria-hidden` and an
  `aria-live` region announces the suggestion plus its accept/dismiss keys instead.
- **Drops into `Field` unchanged**, with id and ARIA wiring passing straight through.

## Examples

Tuning when a suggestion is requested — wait longer after typing stops, and don't ask
at all until there's enough context to complete:

```tsx
<GhostInput
  value={value}
  onValueChange={setValue}
  fetchSuggestion={fetchSuggestion}
  debounceMs={500}
  minChars={12}
/>
```

Reacting to an accepted completion — useful for logging acceptance rate, which is the
honest measure of whether the suggestions are any good:

```tsx
<GhostInput
  value={value}
  onValueChange={setValue}
  fetchSuggestion={fetchSuggestion}
  onAcceptSuggestion={(full) => analytics.track("ghost_accepted", { length: full.length })}
/>
```

The live example at the top of this page is fully interactive — type a few words and
pause to see the completion appear.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` | — | Required. This is a controlled component only. |
| `onValueChange` | `(value: string) => void` | — | Required. |
| `fetchSuggestion` | `(value: string, signal: AbortSignal) => Promise<string \| null \| undefined>` | — | Required. Must resolve to the full continued string, not just the tail. |
| `debounceMs` | `number` | `300` | Delay after the user stops typing before requesting a suggestion. |
| `minChars` | `number` | `1` | Minimum trimmed length before a suggestion is requested. |
| `onAcceptSuggestion` | `(value: string) => void` | — | Fired with the full accepted value. |

All other props forward to the underlying `<input>`.

## Behaviour

- Every keystroke cancels the in-flight request via `AbortSignal` before starting a new
  debounce timer — there is no scenario where a stale response can land after a newer one.
- A response that doesn't start with the value it was requested for is discarded, so a
  slow response can't overwrite what the user is now looking at.
- **Tab**, or **→** with the caret already at the end of the text, accepts. **Esc** dismisses
  without touching the typed value. Any other key just continues typing normally.
- The suggestion is never inserted automatically — there is no "auto-accept after N ms" mode.

## Accessibility

- Implemented as a real `<input>` with a visually-hidden mirror layer, not a
  contentEditable — IME composition, autofill, undo and screen-reader field semantics all
  behave exactly like a plain text input.
- When a suggestion is available, an `aria-live="polite"` region announces it and the
  accept/dismiss keys, since the ghost text itself is `aria-hidden`.
- Right-arrow acceptance only triggers with the caret at the end of the text, so normal
  in-text cursor navigation is never intercepted.

## Why it works this way

The ghost text is rendered as a separate mirror div positioned exactly behind the real <input>, with the typed-text portion set to transparent — not as a styled fake caret or a contentEditable trick. This is the only approach that keeps native input behaviour (IME composition, selection, undo, autofill, screen-reader field semantics) completely intact, at the cost of the mirror div needing identical padding/font/line-height to the input, which is why both come from the same className. The whole request lifecycle — debounce timer, AbortController — lives in refs rather than state so that a rapid keystroke can synchronously cancel the previous request without waiting for a re-render; a state-based cancellation would let a slow response race a fast one and briefly show a stale suggestion. The right-arrow accept only fires when the caret is already at the end of the value (checked via selectionStart/selectionEnd), because otherwise it would silently hijack normal in-text cursor movement, which is a worse failure mode than requiring Tab.

---

Follow the PixelDosa UI rules when building with this component: https://pixeldosa.akshayjayan.com/llms.txt

---

# Human Handoff

> When a person takes over from the agent — and what they're handed.

```bash
npx shadcn@latest add @pixeldosa/human-handoff
```

**Before you use it:** Requires `cn` at `@/lib/utils`. Fill `context` with the facts a colleague would ask for in the first thirty seconds, including what the agent already tried.

## Usage

```tsx
"use client";

import { HumanHandoff } from "@/components/ui/human-handoff";

<HumanHandoff
  stage="waitingForPerson"
  reason="The customer asked for a refund outside the policy window. I can't decide this one."
  context={[
    { id: "customer", label: "Customer", value: "Priya Menon · 3 years, no refunds before" },
    { id: "tried", label: "I already tried", value: "Offered a replacement and a 30% credit. Both declined." },
  ]}
  onTakeOver={take}
/>
```

## Why it exists

Handoffs usually lose everything: the customer repeats themselves, whoever takes over
re-reads a transcript to find three facts, and nobody records what the agent already
tried — so the same rejected remedy gets offered twice.

## Features

- **The context is the component.** The facts a colleague would ask for in the first
  thirty seconds, including what the agent already tried.
- **The reason is in the agent's own words**, so the person knows why it stopped.
- **It works both ways.** Handing a finished job back to the agent is a real stage, not an
  afterthought.
- **Waiting holds completely still**, in the waiting colour, the same treatment approvals
  get.

## Variants

### Waiting for a person

### A person has it

## Props

| Prop | Type | Notes |
| --- | --- | --- |
| `stage` | `"agentHandling" \| "waitingForPerson" \| "personHandling" \| "returnedToAgent"` | Required. |
| `reason` | `string` | Why the agent stepped back, in its words. |
| `context` | `{ id, label, value }[]` | The facts the person receives. |
| `person` | `string` | Who has it now. |
| `waitingFor` | `string` | How long, formatted by you. |
| `onTakeOver` / `takeOverLabel` | `() => void` / `string` | |
| `onReturnToAgent` / `returnLabel` | `() => void` / `string` | |
| `title` | `string` | Defaults to `"Handover"`. |
| `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | Defaults to `3`. |

## Accessibility

- A labelled `<section>`; the context is a description list, so labels and values are
  paired for screen readers.
- The stage is stated in words, not only by colour.
- Nothing animates in any stage.

## When not to use

- **One consequential action awaiting a decision:** use `AI Approval Gate`.
- **A question the agent could answer itself:** use `Agent Ask`.
- **Routing or assignment rules:** that's your queueing system, not this.

## Why it works this way

Stage is a four-value enum rather than a boolean because the return leg is a real state with its own copy, and products that model handoff as 'escalated: true' have nowhere to put the moment a person finishes and the agent resumes. Waiting is styled in the waiting colour with full stillness, the same treatment approvals get, so a queue of handoffs reads at a glance without a separate legend. The context list is `dl` markup rather than free text so a caller can render five facts consistently and a screen reader hears label-and-value pairs, and it sits inside the component rather than being left to a slot because the whole failure mode is teams shipping a handoff button with no payload.

---

Follow the PixelDosa UI rules when building with this component: https://pixeldosa.akshayjayan.com/llms.txt

---

# Inline Citations

> Sources attached to individual claims, where checking takes one step. The supporting passage is shown beside the claim and links straight to that spot in the source.

```bash
npx shadcn@latest add @pixeldosa/inline-citations
```

**Before you use it:** Requires `cn` at `@/lib/utils`. Pass the exact retrieved passage as `quote` — that is what makes checking take one step. Set `support="paraphrased"` when the claim is the model's summary. Leave `source` off rather than attaching a loosely related source.

## Usage

```tsx
"use client";

import { Cite, CitedText } from "@/components/ui/inline-citations";

<CitedText sources={[{ id: "report", title: "Q3 Retention Report", url: "https://…" }]}>
  <p>
    <Cite source="report" quote="30-day retention rose from 41% to 47%.">
      Retention improved by six points in Q3
    </Cite>
    .
  </p>
</CitedText>
```

## Why it exists

Research on AI answers keeps finding the same thing: **people rarely check citations.**
A little number makes an answer *look* verified without anyone verifying it. So the goal
isn't to show sources. It's to make checking one so cheap that people actually do it.

## Features

- **The evidence comes to you.** The popover shows the supporting passage next to the
  claim. No tab switch, no hunting through a PDF.
- **Open at this passage.** The link uses a URL text fragment, so the source opens scrolled to
  the quoted words and highlighted, in browsers that support it.
- **Quoted or summarised.** The popover says whether the source says this or the model
  summarised it.
- **Unsourced claims are marked.** A `<Cite>` with no source shows a dashed `?` and says
  so. An uncited sentence among cited ones otherwise borrows their credibility.
- **You can see what's being cited.** The claim is highlighted while its source is open.
- **The reference list is always there,** for readers without hover and for audits.

## Examples

A claim backed by two sources, each in its own words:

```tsx
<Cite
  source={["survey", "changelog"]}
  support="paraphrased"
  quote={{ survey: "Respondents who used the checklist…", changelog: "4.2 introduces a checklist…" }}
>
  used the guided setup checklist
</Cite>
```

Mapping retrieval results. Keep the retrieved chunk, because it *is* the quote:

```tsx
const sources = retrieved.map((doc) => ({ id: doc.id, title: doc.title, url: doc.url }));

{answer.claims.map((claim) => (
  <Cite key={claim.id} source={claim.sourceIds} quote={claim.passage}>
    {claim.text}
  </Cite>
))}
```

## Props

### CitedText

| Prop | Type | Description |
| --- | --- | --- |
| `sources` | `{ id, title, url?, publisher?, date? }[]` | Required. Numbered in this order. |
| `showReferences` | `boolean` | The reference list. Defaults to `true`. |
| `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | Heading level, so the component fits your page's outline. Defaults to `4`. |

### Cite

| Prop | Type | Description |
| --- | --- | --- |
| `source` | `string \| string[]` | Source id or ids. Omit to mark the claim unsourced. |
| `quote` | `string \| Record<id, string>` | The supporting passage, or one per source. |
| `support` | `"quoted" \| "paraphrased"` | Defaults to `"quoted"`. |

## Accessibility

- Markers are buttons named "Source 1: Q3 Retention Report" or "No source for this claim".
- The popover opens on keyboard focus, sits next to its marker in the DOM so Tab reaches
  its link, and closes with Escape, which returns focus to the marker.
- On touch, tapping a marker opens it and tapping outside closes it.
- The reference list is a real ordered list with ordinary links.

## When not to use

For "why this?" about a whole answer, use `AI Context Surface`. For what the agent did
to find things, use `Tool Call Card`. And don't attach a loosely related source to fill
a gap. Leave `source` off.

## Why it works this way

Designed from one research finding: people rarely verify citations, so a numbered marker is mostly a comfort signal that makes answers look more trustworthy than they are. The design makes the check cheap enough to actually happen. The supporting passage itself appears in the popover beside the claim, so comparing the two needs no navigation. The link opens the source at that passage using a URL text fragment, with start and end words for long quotes because fragments must match exactly. Support is a tier, not a score: 'quoted' vs 'paraphrased'. A claim without a source is marked with a dashed '?' rather than left bare, because an uncited sentence sitting among cited ones borrows their credibility. Numbering comes from the order of the `sources` array rather than render-order registration, so it is identical on server and client. The popover stays in the DOM next to its marker, so Tab moves from marker into the link. It is displayed with the Popover API's top layer and fixed coordinates, which keeps it clear of overflow-hidden containers and transformed ancestors. Without Popover API support it falls back to fixed positioning. It opens on mouse hover after a short delay, with a grace period so the pointer can move into it, and on keyboard focus-visible or tap. Clicking outside dismisses it, and Escape closes it and returns focus. The always-visible reference list is the fallback where hover doesn't exist and the audit view where it does.

---

Follow the PixelDosa UI rules when building with this component: https://pixeldosa.akshayjayan.com/llms.txt

---

# Intent Preview

> The agent restates what it understood and the guesses it made, before any work starts — one click when it's right, one correction when it isn't.

```bash
npx shadcn@latest add @pixeldosa/intent-preview
```

Composes (installed automatically): `ai-action-toolbar`, `select`.

**Before you use it:** Requires `cn` at `@/lib/utils`. Use it only where misreading the request would be costly — long runs, side effects, ambiguous scope. On cheap, reversible actions it is friction.

## Usage

```tsx
"use client";

import { IntentPreview } from "@/components/ui/intent-preview";

<IntentPreview
  interpretation="Reconcile this quarter's flagged invoices and draft a summary of the root cause."
  assumptions={[
    { id: "dataset", label: "Dataset", value: "Q3 Revenue Final.xlsx", options: ["Q3 Revenue.xlsx"] },
    { id: "audience", label: "Summary for", value: "Finance team", options: ["Leadership"] },
  ]}
  boundaries={["Change any invoice", "Send the summary without asking first"]}
  onStart={(values) => run(values)}
  onRephrase={() => focusPrompt()}
/>
```

## Why it exists

An agent interprets a request before it plans anything. If it misreads you there, every
later step builds on the mistake. **The cheapest correction in an agentic run is the
first one** — this puts it where it costs one click.

## Features

- **Guesses arrive filled in.** When they're right, confirming is one click. When one's
  wrong, you correct *that one* in place — no rewriting the prompt.
- **Changes are visible.** The button becomes "Start with changes" once anything was
  corrected, so the confirmation carries information rather than ceremony.
- **Boundaries are part of intent.** "I won't send the summary without asking first" is
  often the thing people most want to know before a run.
- **Holds still** — it's your turn.

## Intent Preview vs Agent Ask

| Question | Agent Ask | Intent Preview |
| --- | --- | --- |
| Can the agent proceed without you? | No — it's missing something | Yes — on its best guess |
| What you do | Supply the answer | Confirm or correct the guesses |
| Cost when things are fine | Always an answer | One click |

## Examples

Only where misreading is expensive. A cheap, reversible action doesn't need it:

```tsx
const needsPreview = task.estimatedSteps > 3 || task.hasSideEffects;
```

Followed by a plan, for runs where both the reading and the steps matter:

```tsx
{phase === "intent" ? <IntentPreview {...intent} onStart={() => setPhase("plan")} /> : null}
{phase === "plan" ? <AgentPlan steps={plan} onRun={execute} /> : null}
```

## Props

| Prop | Type | Description |
| --- | --- | --- |
| `interpretation` | `string` | Required. The request restated in one plain sentence. |
| `assumptions` | `{ id, label, value, options? }[]` | The guesses that filled gaps. `options` makes one correctable. |
| `boundaries` | `string[]` | What the agent will deliberately not do. |
| `onStart` | `(values) => void` | Required. Receives the confirmed values. |
| `onRephrase` | `() => void` | Back to the prompt. |
| `onCancel` | `() => void` | |
| `startLabel` | `string` | Defaults to `"Start"`. |
| `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | Heading level, so the component fits your page's outline. Defaults to `3`. |

## Accessibility

- A labelled `<section>` whose name is the interpretation itself.
- Assumptions are a `<dl>`; corrections use `Select`, a combobox named after the
  assumption ("Dataset") that announces its current value, with keyboard, typeahead and
  touch-sized options.
- Actions are a keyboard toolbar.

## When not to use

A question the agent can't guess the answer to is `Agent Ask`. The steps it will take are
`Agent Plan`. And don't put this in front of cheap, reversible actions — confirmations
nobody needs train people to click through without reading.

## Why it works this way

Built from the model-side view of how agentic runs fail: interpretation happens before planning, and an early misreading compounds through every step that follows. Surfacing the interpretation in one sentence, together with the specific guesses that filled gaps in the request, moves correction to the single point where it is nearly free. Two decisions keep that from becoming friction. First, assumptions arrive pre-filled with the agent's best guess, so the common case — the guess is right — costs one click, and the start label changes to 'Start with changes' only when something was corrected, so the confirmation carries information rather than ceremony. Second, correction happens in place through a Select of alternative readings rather than by rephrasing the whole request, which is both faster and more precise. Boundaries ('I won't…') are included because what an agent will not do is part of its intent and is the thing users most want to know before a run with side effects. It is deliberately distinct from Agent Ask: Ask blocks on missing information the agent cannot guess, whereas Intent Preview is for requests the agent could act on immediately, where acting on a wrong guess would be expensive.

---

Follow the PixelDosa UI rules when building with this component: https://pixeldosa.akshayjayan.com/llms.txt

---

# Live Status Line

> One line saying what an agent is doing right now — replaced as work moves on, cheap enough to live in permanent product chrome.

```bash
npx shadcn@latest add @pixeldosa/live-status-line
```

Composes (installed automatically): `agent-presence`.

**Before you use it:** Requires `cn` at `@/lib/utils`, the `pd-status-swap` keyframe from @pixeldosa/pixeldosa-theme, and @pixeldosa/agent-presence, which it composes for the indicator. Installing this pulls Agent Presence in automatically.

## Usage

```tsx
"use client";

import { LiveStatusLine } from "@/components/ui/live-status-line";

<LiveStatusLine
  state={run.state}
  status="Reading"
  detail="invoices/2026-q3.csv"
  startedAt={run.startedAt}
  onCancel={run.abort}
/>
```

## Features

- **It replaces, it doesn't accumulate.** That's the whole distinction from its
  neighbours — and it's why this is cheap enough to leave in a toolbar or sidebar
  footer permanently. History belongs to `Reasoning Stream` and
  `Chain-of-Thought Timeline`.
- **Composes `Agent Presence`** for the indicator rather than drawing its own dots, so
  the turn-taking grammar holds here for free — a `suggesting` or `awaitingApproval`
  status stops moving without this component knowing anything about it.
- **Layout can't jitter.** A minimum row height means changing text length never
  reflows the container, and the *detail* truncates before the verb does — so "Reading"
  stays legible when a long path can't.
- **The elapsed counter ticks itself**, rather than making you re-render once a second
  for a display detail.
- **Swaps once per real change** — keyed on the status text, so a re-render with
  unchanged text never re-animates.

## Variants

### Working, with an object

### Thinking

### Your turn — it stops

Inherited from `Agent Presence`: the indicator holds still because nothing proceeds
until you act.

### Complete

## Examples

In permanent chrome — a sidebar footer or toolbar, where it costs one row:

```tsx
<footer className="border-t px-3">
  <LiveStatusLine state={run.state} status={run.status} startedAt={run.startedAt} onCancel={run.abort} />
</footer>
```

Per row in a table, where each row has its own agent job:

```tsx
{rows.map((row) => (
  <td key={row.id}>
    <LiveStatusLine state={row.state} status={row.status} detail={row.target} />
  </td>
))}
```

Omit `startedAt` where elapsed time isn't meaningful — a sub-second action doesn't need
a stopwatch:

```tsx
<LiveStatusLine state="working" status="Saving" />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `state` | `AgentState` | — | Required. Agent Presence's vocabulary. |
| `status` | `string` | — | Required. The current micro-action. |
| `detail` | `string` | — | What it's acting on. Truncates before the verb. |
| `startedAt` | `number \| Date` | — | Drives the live elapsed counter. |
| `onCancel` | `() => void` | — | Shown while the agent is active. |
| `indicator` | `"mark" \| "line"` | `"mark"` | The agent's drawn head, or three dots for the densest rows. |

All other props forward to the wrapping `<div>`.

## Accessibility

- The status text is announced through `Agent Presence`'s `aria-live` region — one
  announcement channel, not two competing ones.
- The elapsed counter uses `tabular-nums`, so the line doesn't shift as seconds tick.
- Stop is a real keyboard-reachable `<button>` with its hit area extended to ~44px
  while staying visually compact.
- Under `prefers-reduced-motion` the swap is dropped; the text simply changes, which
  loses nothing since the information was always the words.

## When not to use

The reasoning text itself is `Reasoning Stream`. A per-artifact generation surface is
`Generation Placeholder`. The whole turn's history is `Chain-of-Thought Timeline`. And
this isn't a toast — it describes ongoing work, it doesn't announce a completed event
and disappear.

## Why it works this way

The defining constraint is that this component replaces rather than accumulates. Accumulation is what makes agent activity surfaces expensive — a growing list needs scroll management, virtualisation at length, and a decision about when to collapse. Holding exactly one line keeps it cheap enough to live permanently in product chrome, and pushes the history question to Reasoning Stream and Chain-of-Thought Timeline where it belongs. It composes Agent Presence's `line` form rather than drawing its own dots, which is the system's compose-don't-reinvent rule applied where it genuinely fits: the turn-taking grammar then holds here for free, including the fact that a `suggesting` or `awaitingApproval` status stops moving. Two layout decisions prevent the jitter this pattern usually has: a minimum row height, so text of varying length cannot reflow the container around it, and truncation applied to the detail rather than the verb, so 'Reading' remains legible when a long filename cannot be. The elapsed counter is the one place this system deliberately breaks its own 'the caller owns async state' convention — every other component takes progress, busy and duration as props — because a live counter would otherwise force the consumer to re-render once a second purely for a display detail. The interval is only started while the agent is actually active, and never when no `startedAt` was supplied.

---

Follow the PixelDosa UI rules when building with this component: https://pixeldosa.akshayjayan.com/llms.txt

---

# Media Result

> A finished generated image, video or clip — with what made it and whether content credentials are attached.

```bash
npx shadcn@latest add @pixeldosa/media-result
```

**Before you use it:** Requires `cn` at `@/lib/utils`. Render the media yourself and give images real alt text. Pass `credentials.attached: false` honestly — the absence is the useful signal.

## Usage

```tsx
"use client";

import { MediaResult } from "@/components/ui/media-result";

<MediaResult
  title="Bottle on stone, warm light"
  aspectRatio="4 / 5"
  madeBy="Made with Imagen 4 · today at 14:02"
  credentials={{ attached: true, detail: "Content Credentials + invisible watermark", href: verifyUrl }}
  actions={[{ id: "use", label: "Use in the post", primary: true }, { id: "download", label: "Download" }]}
  onAction={handle}
>
  <img src={url} alt="A dark bottle on a stone surface in warm light" className="size-full object-cover" />
</MediaResult>
```

## Why it exists

Since August 2026, the EU AI Act's Article 50 and California's SB 942 both require
machine-readable disclosure of AI-generated media, and the big generators now sign their
output with Content Credentials and an invisible watermark. The interface should say so,
next to the result — and say when it hasn't.

## Features

- **Provenance in words**, beside the media: what made it, when, and whether credentials
  are attached.
- **Unsigned is a visible state.** When credentials are missing the frame says so in the
  waiting colour, rather than staying quiet.
- **A link to verify**, when you have one.
- **Your own note** for usage rights, and actions with one primary.
- **The layout never jumps:** set `aspectRatio` to the output's shape.

## Variants

### Signed

### Not signed yet

## Props

| Prop | Type | Notes |
| --- | --- | --- |
| `children` | `ReactNode` | Required. The media itself; give images real alt text. |
| `title` | `string` | What it is, in the user's words. |
| `aspectRatio` | `string` | Defaults to `"1 / 1"`. |
| `madeBy` | `string` | Model and time, formatted by you. |
| `credentials` | `{ attached, detail?, href? }` | Pass `attached: false` honestly. |
| `note` | `string` | Usage rights, or your own caveat. |
| `actions` / `onAction` | `{ id, label, primary? }[]` | At most one primary. |

## Accessibility

- A `figure` with a `figcaption`, so the title and provenance are associated with the
  media by the platform.
- The provenance state is text, not only an icon or a colour.
- The caption sits outside the media box, so it's never baked into a screenshot of the
  image.

## When not to use

- **Work still in progress:** use `Generation Job`.
- **A grid of candidates:** use `Variation Grid`.
- **A general "AI generated" badge** on text: use `AI Disclosure`.

## Why it works this way

`credentials` is a small object rather than a boolean because the three questions a team has are different: is it signed, what was applied, and where can it be checked. Treating the unsigned case as a visible state in the waiting colour — instead of simply omitting the line — is the deliberate inversion here: products that only show a badge when signing succeeds make an unsigned file indistinguishable from a file nobody thought about, which is precisely the one that must not ship under the 2026 disclosure rules. The frame is a `figure` with a `figcaption`, so provenance and title are associated with the media by the platform rather than by proximity, and the whole caption stays outside the media box so it is never baked into a screenshot of the image itself.

---

Follow the PixelDosa UI rules when building with this component: https://pixeldosa.akshayjayan.com/llms.txt

---

# Message

> One turn of a conversation, with reasoning, tool calls, citations and the answer kept together in the order the work happened.

```bash
npx shadcn@latest add @pixeldosa/message
```

**Before you use it:** Requires `cn` at `@/lib/utils`. Bring your own markdown renderer and wrap its output in `MessageContent`. Set `status` from the stream itself: 'done' only when the stream closes, 'stopped' when the user aborted.

## Usage

```tsx
"use client";

import { Message, MessageContent } from "@/components/ui/message";

<Message role="user">Why did churn go up in August?</Message>

<Message
  role="assistant"
  author="Assistant"
  status={stream.status}
  error={stream.error}
  onRetry={retry}
  onContinue={resume}
  actions={<AIActionToolbar actions={answerActions} onAction={handle} />}
>
  <ReasoningStream steps={stream.reasoning} isStreaming={stream.phase === "reasoning"} />
  <ToolCallGroup calls={stream.toolCalls} />
  <MessageContent>
    <Markdown>{stream.text}</Markdown>
  </MessageContent>
</Message>
```

## Why it exists

An AI answer isn't only text. It's the reasoning, what the model looked up and what it
concluded, and those belong to one turn. Split them into separate rows and the reading
order breaks, screen readers lose the thread, and it's no longer clear which tool
calls produced which answer.

## Features

- **The turn is the container.** Children render in order: reasoning, tools, then the answer.
- **Real streaming, no fake typing.** Text appears as chunks arrive, with a small
  quantized cursor at the end.
- **No acting on half an answer.** Actions stay hidden until the message is `done`.
- **Nothing is thrown away.** A failed turn keeps what arrived, says why and offers Retry. A
  stopped turn is labelled incomplete, with Continue.
- **Room to read.** User turns are compact bubbles. Assistant turns use the full width for
  code, tables and long answers.
- **Any markdown renderer.** `MessageContent` styles the HTML it produces.

## Statuses

| `status` | Looks like | Offers |
| --- | --- | --- |
| `streaming` | Text as it arrives, plus the cursor | Nothing yet |
| `done` | Final answer | `actions` |
| `failed` | Partial text, dimmed, plus an error | Retry |
| `stopped` | Partial text, labelled incomplete | Continue, Start over |

## Examples

Mapping stream events, whatever your runtime:

```tsx
const status =
  aborted ? "stopped" : error ? "failed" : streamClosed ? "done" : "streaming";
```

A user message with edit, shown on hover and always visible on touch:

```tsx
<Message role="user" actions={<button onClick={edit}>Edit</button>}>
  {text}
</Message>
```

## Props

### Message

| Prop | Type | Description |
| --- | --- | --- |
| `role` | `"user" \| "assistant"` | Required. |
| `status` | `"streaming" \| "done" \| "failed" \| "stopped"` | Assistant turns. Defaults to `"done"`. |
| `author` | `ReactNode` | Also names the article for screen readers when it's a string. |
| `avatar` | `ReactNode` | Assistant turns. |
| `meta` | `ReactNode` | Timestamp or similar. |
| `actions` | `ReactNode` | Shown when `done`, or on hover and focus for user turns. |
| `error` | `string` | Shown when `failed`. |
| `onRetry` | `() => void` | |
| `onContinue` | `() => void` | Offered when `stopped`. |
| `showCursor` | `boolean` | The streaming cursor. Defaults to `true`; turn it off while reasoning or a tool call already shows progress. |

### MessageContent

A `div` with typography for paragraphs, lists, headings, links, inline code and quotes.

## Accessibility

- Each turn is an `<article>` named "You said" or "Assistant said".
- `aria-busy` is set while streaming, so the turn isn't announced piece by piece.
- Errors render in an alert region.
- The streaming cursor is decorative and static under reduced motion.

## When not to use

Use `Message Scroller` for the list itself: scrolling, jumping to the latest message and
announcements. For a single generated artifact with no conversation, use `Prompt Composer` and
show the result directly.

## Why it works this way

Designed as the turn, not the text bubble. An assistant reply contains reasoning, tool calls, citations and prose, and treating those as siblings of the message breaks both reading order and accessibility. Here they are children of one `<article>`, named 'You said' or '<author> said' and marked `aria-busy` while streaming, so assistive tech treats the turn as one unit that is still arriving. Status is caller-owned because only the stream knows it. Each status has distinct UI, and none discards content: failed keeps the partial answer (dimmed) with an actionable error in an alert region and Retry; stopped labels the answer incomplete with Continue and Start over. Actions on assistant turns render only once the status is 'done', because copying or applying half an answer is an error the interface shouldn't invite. The user bubble keeps its actions hidden until hover or focus-within, and always shows them on touch devices via `(hover: none)`. Assistant turns have no bubble so code, tables and long prose get the full width. `MessageContent` carries typography for the HTML any markdown renderer emits, so the component stays renderer-agnostic and dependency-free.

---

Follow the PixelDosa UI rules when building with this component: https://pixeldosa.akshayjayan.com/llms.txt

---

# Message Scroller

> The conversation list that follows new messages only while you're following along, and never moves under you while you read.

```bash
npx shadcn@latest add @pixeldosa/message-scroller
```

**Before you use it:** Requires `cn` at `@/lib/utils`. Give children stable `key`s, because history prepends are detected by the first key changing. Give the scroller a height (`h-[…]` or `flex-1` in a flex column). Set `announcement` when a reply finishes.

## Usage

```tsx
"use client";

import { Message, MessageContent } from "@/components/ui/message";
import { MessageScroller } from "@/components/ui/message-scroller";

<MessageScroller className="h-[600px]" announcement={lastFinished} onReachTop={loadOlder}>
  {messages.map((message) => (
    <Message key={message.id} role={message.role} status={message.status}>
      <MessageContent>{message.content}</MessageContent>
    </Message>
  ))}
</MessageScroller>
```

## Why it exists

The most common chat bug: you scroll up to reread something while the assistant is still
answering, and the page keeps dragging you back down. The scroller treats "should I
follow?" as a question about **you**, not about the content.

## Features

- **Follows only while you're at the bottom.** Scroll up and it stops. Nothing moves under you.
- **Jump to latest.** A pill appears when you're scrolled away, counting messages that
  arrived: "2 new messages".
- **History loads without a jump.** When older messages arrive above, your view stays exactly where it was.
- **Streaming is followed too,** not just new messages, because a growing answer adds no new elements.
- **Announces finished messages, not tokens.** Screen readers hear what you pass as `announcement`.
- **Keyboard scrollable.** The region is focusable and named "Conversation".

## Examples

Full-height chat layout:

```tsx
<div className="flex h-dvh flex-col">
  <MessageScroller className="flex-1">{turns}</MessageScroller>
  <PromptComposer onSubmit={send} />
</div>
```

Announce a finished reply once:

```tsx
onFinish={(message) => setAnnouncement(`Assistant replied: ${message.text.slice(0, 120)}`)}
```

## Props

| Prop | Type | Description |
| --- | --- | --- |
| `children` | `ReactNode` | Messages with stable `key`s. |
| `announcement` | `string` | Set when a message finishes. |
| `onReachTop` | `() => void` | Fires near the top. Load older messages here. |
| `label` | `string` | Region name. Defaults to `"Conversation"`. |

## Accessibility

- A focusable, named region, so it can be scrolled with the keyboard.
- A polite status region carries `announcement`. It isn't a live log, which would read every token.
- The jump pill is a real button and uses instant scrolling under reduced motion.

## When not to use

Not for feeds where the newest item belongs at the top. For a reasoning trace inside one
message, `Reasoning Stream` already scrolls itself the same way.

## Why it works this way

Auto-scroll is where chat interfaces most often break trust: a stream drags the view down while someone is reading an earlier answer. Here 'pinned' is a fact about the reader, recomputed from their own scroll position with a 48px tolerance. Following happens only while pinned, both when children are added (layout effect) and when the last message grows during streaming (a ResizeObserver on the content, since token growth adds no children). While unpinned, added children are counted into the jump pill. A smooth jump sets a guard, so the intermediate 'not at bottom' frames of the animation don't unpin and flash the pill back. A 700ms fallback lands on the bottom even if streaming moved the target mid-animation. Prepended history is detected by the first child's key changing alongside a higher count, and compensated by adding the height delta to scrollTop in a layout effect before paint. Native `overflow-anchor` is disabled, so browsers with and without support behave identically. Accessibility uses a named, focusable region for keyboard scrolling and a separate polite status for caller-supplied announcements, because a live log would read every streamed token.

---

Follow the PixelDosa UI rules when building with this component: https://pixeldosa.akshayjayan.com/llms.txt

---

# Overlay Motion Primitive

> The shared enter/exit animation layer for Dialog, Sheet, Popover and Drawer — a scrim plus a placement-aware content panel, both driven by motion tokens.

```bash
npx shadcn@latest add @pixeldosa/overlay
```

**Before you use it:** Render OverlayScrim and OverlayContent inside AnimatePresence, controlled by the same boolean/state that drives your Radix primitive's open prop. Neither component owns mount/unmount timing — AnimatePresence does, via whatever is conditionally rendering them.

## Usage

Compose it underneath a Radix primitive — Radix owns focus trapping, dismiss-on-outside-
click and portalling; Overlay owns only the motion.

```tsx
import * as Dialog from "@radix-ui/react-dialog";
import { AnimatePresence, OverlayContent, OverlayScrim } from "@/components/ui/overlay";

export function ConfirmDialog({ open, onOpenChange, children }: Props) {
  return (
    <Dialog.Root open={open} onOpenChange={onOpenChange}>
      <AnimatePresence>
        {open ? (
          <Dialog.Portal forceMount>
            <Dialog.Overlay asChild>
              <OverlayScrim />
            </Dialog.Overlay>
            <Dialog.Content asChild>
              <OverlayContent placement="center" className="fixed left-1/2 top-1/2 w-96 -translate-x-1/2 -translate-y-1/2 p-6">
                {children}
              </OverlayContent>
            </Dialog.Content>
          </Dialog.Portal>
        ) : null}
      </AnimatePresence>
    </Dialog.Root>
  );
}
```

For a Sheet or Drawer, swap `placement` to `"right"`, `"left"`, `"top"` or `"bottom"` and
position `OverlayContent` against that edge instead of centering it — the translate
distance and easing stay identical, only the axis changes.

## Features

- **One motion layer for four patterns.** Dialog, Sheet, Popover and Drawer share the
  same scrim and panel transition — only `placement` changes, so they can't drift apart
  into four slightly different fades.
- **A strict division of labour**: Radix owns focus trapping, dismissal and portalling;
  Overlay owns motion and nothing else. It adds no accessibility semantics of its own
  precisely so it can't contradict the primitive it wraps.
- **Exit animations that actually run**, via `AnimatePresence` plus `forceMount` — the
  element stays mounted long enough to animate out instead of vanishing.
- **Token-driven throughout** — duration and easing come from the motion tokens, so
  retuning the system's rhythm retunes every overlay at once.

## Examples

Five placements, one component. `center` adds a slight scale-in; the edge placements
translate in from their edge with identical distance and easing:

```tsx
<OverlayContent placement="center" className="fixed left-1/2 top-1/2 w-96 -translate-x-1/2 -translate-y-1/2 p-6" />
```

A right-hand sheet — position it against the edge and switch `placement`; nothing else
changes:

```tsx
<OverlayContent placement="right" className="fixed inset-y-0 right-0 w-80 p-6">
  {children}
</OverlayContent>
```

A bottom drawer, which is usually the right mobile counterpart to a centered dialog:

```tsx
<OverlayContent placement="bottom" className="fixed inset-x-0 bottom-0 rounded-b-none p-6">
  {children}
</OverlayContent>
```

`forceMount` is not optional — without it Radix unmounts the content immediately and
`AnimatePresence` never gets to run the exit:

```tsx
<Dialog.Portal forceMount>
  <Dialog.Overlay asChild>
    <OverlayScrim />
  </Dialog.Overlay>
  {/* … */}
</Dialog.Portal>
```

## Props

### OverlayScrim

Forwards all `motion.div` props. No component-specific props.

### OverlayContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `placement` | `"center" \| "top" \| "bottom" \| "left" \| "right"` | `"center"` | Which edge the panel translates in from. `center` also applies a slight scale-in. |

All other props forward to `motion.div`.

## Accessibility

This primitive is motion-only and carries no accessibility semantics of its own — those
come entirely from whichever Radix primitive (`Dialog`, `Popover`, custom `Sheet`) you
render it inside of. Always use `forceMount` on the Radix portal/content so `AnimatePresence`
can run the exit animation before the element actually unmounts.

## Why it works this way

Extracted as its own primitive rather than duplicated inside Dialog, Sheet, Popover and Drawer because those four are the same motion problem (scrim fade + panel translate/scale) wearing four different Radix primitives underneath. Without this, four components would each hand-roll slightly different durations the first time someone patches one of them, and the system's visual coherence — the actual point of a token-driven motion scale — degrades one component at a time. Deliberately excludes dismiss-on-click-outside, focus trapping and portalling: those are interaction semantics Radix already solves correctly, and re-solving them here would create two competing sources of truth for overlay behaviour.

---

Follow the PixelDosa UI rules when building with this component: https://pixeldosa.akshayjayan.com/llms.txt

---

# Parameter Panel

> The controls beside the prompt — pick a look from previews instead of naming it.

```bash
npx shadcn@latest add @pixeldosa/parameter-panel
```

**Before you use it:** Requires `cn` at `@/lib/utils`. Give every option a real `preview` where you can — a thumbnail of that style, a shape for an aspect ratio — and never ship an option that is only an icon.

## Usage

```tsx
"use client";

import { ParameterPanel } from "@/components/ui/parameter-panel";

<ParameterPanel
  groups={groups}
  values={values}
  onChange={(groupId, optionId) => setValues({ ...values, [groupId]: optionId })}
  summary="4 photographic square images · 40 credits"
  onReset={reset}
/>
```

## Why it exists

Research on generative tools calls the core problem the articulation barrier: people can
picture what they want but can't name it, and style vocabulary ("tilt-shift",
"synth-wave") is exactly the knowledge they lack. Showing options beats asking people to
describe them.

## Features

- **Recognition, not recall.** Every option can carry a small preview: a thumbnail of that
  style, a shape for an aspect ratio.
- **Labels always ship.** Studies of prompt controls found novel icons are misread almost
  universally, so an option is never an icon alone.
- **Price on the option.** Anything that changes the cost says so where it's chosen, not
  in a bill afterwards.
- **One help line per group**, under the current choice, instead of help text on every
  option.
- **Real radio groups.** Arrow keys, grouping and announcement come from the platform.

## Props

| Prop | Type | Notes |
| --- | --- | --- |
| `groups` | `{ id, label, options }[]` | Options carry `label`, `preview?`, `costNote?`, `detail?`. |
| `values` | `Record<string, string>` | Chosen option id per group id. |
| `onChange` | `(groupId, optionId) => void` | Required. |
| `summary` | `string` | What the choices add up to. |
| `onReset` | `() => void` | |
| `title` | `string` | Defaults to `"Settings"`. |
| `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | Defaults to `3`. |

## Accessibility

- Each group is a `fieldset` with a `legend`; options are radio inputs, so arrow keys work
  and the group is announced as a group.
- Previews are decorative and hidden; the label is the accessible name.
- Focus shows the standard ring on the whole option, not just the hidden input.

## When not to use

- **A settings page.** This belongs beside the thing it affects.
- **Free-text parameters:** put those in `Prompt Composer`'s controls.
- **Twenty options in a group:** that's a picker or a search, not a row of previews.

## Why it works this way

Each group is a real `fieldset` of radio inputs with the input visually hidden behind its label, so arrow-key navigation, grouping and announcement come from the platform rather than from a custom roving-tabindex implementation that would have to be re-tested in every host app. The chosen value is caller-owned per group id, which lets a product persist presets, share them in a URL, or drive them from a model's suggestion without the component holding a second source of truth. `costNote` sits on the option rather than being derived, because only the caller knows how its pricing composes — quality multiplied by count multiplied by resolution is not something a component can infer from labels. `detail` renders once per group under the current choice instead of on every option, which keeps a panel of twelve options from becoming a wall of help text.

---

Follow the PixelDosa UI rules when building with this component: https://pixeldosa.akshayjayan.com/llms.txt

---

# Progressive Reveal

> Reveals a growing collection of items one at a time as they arrive, with a stable layout and no per-character typewriter effect.

```bash
npx shadcn@latest add @pixeldosa/progressive-reveal
```

**Before you use it:** Requires `cn` at `@/lib/utils`. Is a plain generic function component (no `forwardRef`) since nothing here needs an imperative handle and `forwardRef` has poor generic-type ergonomics. Pass a real `keyExtractor` whenever the source array might ever be spliced rather than purely appended — without one, index-based keys can misattribute 'already seen' identity to the wrong item if earlier entries are removed or reordered.

## Usage

```tsx
"use client";

import * as React from "react";
import { ProgressiveReveal } from "@/components/ui/progressive-reveal";

export function SearchResults() {
  const [items, setItems] = React.useState<Result[]>([]);
  const [streaming, setStreaming] = React.useState(false);

// ...append to `items` as results arrive from your stream...

return (
    <ProgressiveReveal
      items={items}
      keyExtractor={(item) => item.id}
      isStreaming={streaming}
      renderItem={(item) => <ResultCard result={item} />}
    />
  );
}
```

Each item is given its entrance transition exactly once — an item already present on a
prior render keeps its existing DOM node and is never remounted, so its animation can
never replay, no matter how often the parent re-renders.

### Why not a typewriter effect

The full value of each item already exists the moment it arrives — revealing it
character-by-character would misrepresent something already fully generated as being
"typed live." This component only ever fades a whole item in, never streams its
content.

### Grid layout

```tsx
<ProgressiveReveal items={cards} layout="grid" renderItem={(card) => <Card {...card} />} />
```

## Features

- **Animate once, never replay.** Entrance is enforced by React's own keyed
  reconciliation, not a timer — an item present on a prior render keeps its DOM node,
  so no amount of parent re-rendering can restart its transition.
- **No fabricated typing.** Items fade in whole. Content that already exists in full is
  never revealed character-by-character (DESIGN.md §3.3).
- **Stable layout while streaming** — items append without shifting what's already
  been read.
- **Announced as a running count**, once, through a single `aria-live` region rather
  than one announcement per arrival, so a fast stream doesn't flood a screen reader.
- **Two layouts** — `stack` and `grid` — sharing one entrance behaviour.

## Examples

A grid of results rather than a vertical stack:

```tsx
<ProgressiveReveal
  items={cards}
  layout="grid"
  keyExtractor={(card) => card.id}
  renderItem={(card) => <ResultCard result={card} />}
/>
```

Showing the trailing "More loading…" indicator while the stream is still open — flip
`isStreaming` to `false` the moment it closes, so the indicator never outlives the work
it represents:

```tsx
<ProgressiveReveal
  items={results}
  keyExtractor={(result) => result.id}
  isStreaming={status === "streaming"}
  renderItem={(result) => <ResultRow result={result} />}
/>
```

Pass a real `keyExtractor` whenever the array might be spliced rather than purely
appended — the array index is only a safe key while items are append-only:

```tsx
<ProgressiveReveal items={items} keyExtractor={(item) => item.id} renderItem={renderItem} />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | `T[]` | — | Required. The current known items; append to it as more arrive. |
| `renderItem` | `(item: T, index: number) => React.ReactNode` | — | Required. |
| `keyExtractor` | `(item: T, index: number) => React.Key` | array index | Use a real key whenever the array might be spliced, not purely appended. |
| `isStreaming` | `boolean` | `false` | Shows a trailing "More loading…" indicator. |
| `layout` | `"stack" \| "grid"` | `"stack"` | |

## Accessibility

- Item arrivals are announced through a single `aria-live="polite"` region reporting
  the running count, not one announcement per item, so a fast stream doesn't spam a
  screen reader.
- The streaming indicator's text is the real signal; its pulsing dot is decorative.
- Under `prefers-reduced-motion`, per-item entrance becomes instant and the pulse stops
  oscillating, but the "More loading…" text stays exactly as informative.

## When not to use

Streaming prose is a different problem — reach for an existing chat/response
component (e.g. Vercel AI Elements) instead. A single value that changes over time is
`Smart Field` or `Diff Accept`, not a collection.

## Why it works this way

Enforces 'animate a new item in exactly once' by relying on React's own keyed reconciliation instead of hand-rolled 'already seen' tracking: each item is wrapped in a small RevealItem component keyed by keyExtractor (or index), which mounts fresh — and therefore plays its entrance transition — only the first time its key appears in the list; on every subsequent render where that key was already present, React reuses the existing DOM node and the component is not remounted, so the animation structurally cannot replay. This is simpler and more reliable than maintaining a Set of seen keys by hand, which is easy to get subtly wrong around React's own re-render timing. Scoped deliberately to structured collections (rows, cards), not prose — an append-only list of discrete items is inherently more layout-stable than a single growing text block, since new rows appear below existing content without reflowing it, which is also why this differs from and does not compete with Vercel AI Elements' prose-streaming components (see the roadmap's North Star Reconciliation table).

---

Follow the PixelDosa UI rules when building with this component: https://pixeldosa.akshayjayan.com/llms.txt

---

# Prompt Composer

> A request composer that isn't a blank chat box. Free text, structured controls for tone, length, audience and format, and attachments for context.

```bash
npx shadcn@latest add @pixeldosa/prompt-composer
```

Composes (installed automatically): `select`.

**Before you use it:** Requires `cn` at `@/lib/utils`. Put anything users would otherwise type as boilerplate ("make it friendlier, keep it short") into `controls`, and turn `values` into the prompt on your side. Upload in `onAttachFiles` and keep `attachments` in your state.

## Usage

```tsx
"use client";

import { PromptComposer } from "@/components/ui/prompt-composer";

<PromptComposer
  controls={[
    { id: "tone", label: "Tone", options: ["Neutral", "Friendly", "Formal"], defaultValue: "Neutral" },
    { id: "length", label: "Length", options: ["Short", "Medium", "Long"], defaultValue: "Medium" },
  ]}
  attachments={attachments}
  onAttachFiles={upload}
  onRemoveAttachment={remove}
  busy={generating}
  onStop={abort}
  onSubmit={({ text, values, attachments }) => generate(buildPrompt(text, values), attachments)}
/>
```

## Why it exists

A blank box asks people to be good at prompting. "Make it friendlier, keep it short,
it's for customers" isn't creative input. It's a **specification**, and typing it as
prose every time is inconsistent and invisible until the result comes back wrong. The
composer turns it into controls you can see before you send.

## Features

- **Specification as pills.** "Tone: Friendly" is a `Select` pill, so it works with a
  keyboard, typeahead and a screen reader, and its list is drawn in the system's own
  surface. Pills changed from their default are outlined, so the non-default parts of
  the request stand out.
- **Enter to send, Shift+Enter for a new line.** Enter doesn't send while an input
  method (IME) is composing. Japanese or Chinese typists don't send half a sentence.
- **Attach any way.** Use the button, drag and drop, or paste. Upload status is shown on each
  file, and sending waits for uploads with a visible reason.
- **Stop while generating.** Send becomes Stop and stays reachable.
- **A count only when it matters.** It appears in the last 10% before `maxLength`.
- **Suggestions fill, they don't send.**

## Examples

Turn values into the prompt on your side, where you control the wording:

```tsx
function buildPrompt(text, { tone, length, audience, format }) {
  return `Write a ${length.toLowerCase()} ${format.toLowerCase()} for ${audience.toLowerCase()} in a ${tone.toLowerCase()} tone.\n\n${text}`;
}
```

Uploads stay yours. Report status back:

```tsx
onAttachFiles={(files) => {
  for (const file of files) {
    const id = crypto.randomUUID();
    add({ id, name: file.name, status: "uploading" });
    uploadFile(file).then(
      () => update(id, { status: "ready" }),
      () => update(id, { status: "failed" }),
    );
  }
}}
```

## Props

| Prop | Type | Description |
| --- | --- | --- |
| `onSubmit` | `({ text, values, attachments }) => void` | Required. |
| `controls` | `{ id, label, options, defaultValue }[]` | Options are strings or `{ value, label }`. |
| `attachments` | `{ id, name, detail?, status? }[]` | `status`: `"uploading" \| "ready" \| "failed"`. |
| `onAttachFiles` | `(files: File[]) => void` | Enables attach, drop and paste. |
| `onRemoveAttachment` | `(id) => void` | |
| `accept` | `string` | Passed to the file input. |
| `suggestions` | `string[]` | Shown while the text is empty. |
| `busy` / `onStop` | `boolean` / `() => void` | Send becomes Stop. |
| `maxLength` | `number` | |
| `submitLabel` | `string` | Defaults to `"Generate"`. |
| `label` | `string` | Accessible name for the text area. |
| `clearOnSubmit` | `boolean` | Defaults to `true`. Controls keep their values. |
| `value` / `onValueChange` | `string` / `(value) => void` | Controlled text, e.g. to fill the composer from a suggestion. |

## Accessibility

- The text area has a label and is described by the keyboard hint.
- Each control is a `Select` combobox named after its label ("Tone") that announces its
  current value; the visible "Tone:" prefix is hidden from screen readers so it isn't
  read twice.
- Send uses `aria-disabled`, so it stays focusable, and the reason it's blocked is shown and announced.
- Attachment remove buttons are named after the file.

## When not to use

This isn't a chat input. There's no thread and no history. Use it where a request
produces an artifact. For redirecting an agent that's already running, use `Agent Steer`.

## Why it works this way

Exists because the system argues against making every AI feature a blank chat box and needed an alternative. The composer splits a request into what only words can say (the text) and what is really a specification (controls), because specifications typed as prose are inconsistent and invisible until the result comes back wrong. Controls are Select pills: keyboard, typeahead and screen reader behaviour come from Select, each pill sizes to its current choice rather than its longest option, and the open list is drawn in the system's own surface instead of the platform's menu. A changed value gets a stronger outline, so the non-default parts of the request stand out. Details are handled where composers usually slip. Enter is ignored while `isComposing`, so IME users confirming a candidate don't send half a sentence. The text area autosizes from scrollHeight up to 240px, because `field-sizing: content` isn't universal yet. Send is `aria-disabled`, not `disabled`, so it stays focusable and the blocked reason ('Waiting for attachments to finish uploading') is shown and announced. The count appears only in the last 10% before `maxLength`. The file input is reset after each pick, so the same file can be picked again. Uploads are the caller's, and the composer only reflects their status. It stays headless about what happens next: the caller assembles the prompt from `values`.

---

Follow the PixelDosa UI rules when building with this component: https://pixeldosa.akshayjayan.com/llms.txt

---

# Reasoning Stream

> An agent's reasoning as it arrives — a two-line ticker while it streams, folding to "Thought for 12s" once the answer exists.

```bash
npx shadcn@latest add @pixeldosa/reasoning-stream
```

**Before you use it:** Requires `cn` at `@/lib/utils` and the `pd-fade-in` keyframe supplied by @pixeldosa/pixeldosa-theme's css block. Show reasoning *summaries* where the provider exposes them; raw private chain-of-thought should not be presented to end users as fact.

## Usage

```tsx
"use client";

import { ReasoningStream } from "@/components/ui/reasoning-stream";

export function Answer({ run }: { run: AgentRun }) {
  return (
    <>
      <ReasoningStream
        steps={run.reasoningSummaries}
        isStreaming={run.status === "reasoning"}
        durationMs={run.reasoningMs}
      />
      <p>{run.answer}</p>
    </>
  );
}
```

`steps` is an array rather than a raw string because providers emit reasoning
*summaries* as discrete parts — deciding where one thought ends is your business, not
the component's.

## Features

- **It folds away when the answer arrives.** This is the whole thesis, not a
  convenience. Reasoning is scaffolding: useful while the thing is being built, noise
  once it stands. A panel left expanded after the answer lands makes every answer look
  like it needs justifying.
- **The duration is the useful part.** "Thought for 12s" answers *was this worth
  waiting for* better than any quantity of reasoning text. It's measured, never
  estimated.
- **Scroll anchoring done properly.** It follows new content only while you're at the
  bottom. The moment you scroll up to read something, it holds your position and offers
  "Jump to latest" instead of yanking you back.
- **Never fake typing.** Steps fade in whole. Text that already arrived is never
  revealed character-by-character, because that misrepresents content the model had
  already finished producing.
- **Animate once, never replay** — enforced by React's keyed reconciliation, not a
  timer.

## Variants

### Streaming

A ticker, newest at the bottom, older lines masked out above. It reads as a process,
which is what it still is.

### Complete

Collapsed by default. The trace is one click away for anyone who wants it, and out of
the way for everyone who doesn't.

### Expanded

## Examples

Mapping from the AI SDK, where reasoning is a distinct part type:

```tsx
const reasoning = message.parts
  .filter((part) => part.type === "reasoning")
  .map((part) => part.text);

<ReasoningStream steps={reasoning} isStreaming={status === "streaming"} />
```

Pairing with `Agent Presence` — the indicator says *that* it's thinking, this says
*what* it's thinking:

```tsx
<AgentPresence state="thinking" form="line" size="sm" />
<ReasoningStream steps={reasoning} isStreaming />
```

Opening by default for a debugging or evaluation surface, where the trace *is* the
content rather than the scaffolding:

```tsx
<ReasoningStream steps={trace} durationMs={elapsed} defaultExpanded />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `steps` | `string[]` | — | Required. Oldest first; append as they arrive. |
| `isStreaming` | `boolean` | `false` | Shows the ticker and the "Jump to latest" affordance. |
| `durationMs` | `number` | — | Measured elapsed time, shown on completion. |
| `label` | `string` | `"Thinking"` | Verb shown while streaming. |
| `defaultExpanded` | `boolean` | `false` | |

All other props forward to the wrapping `<div>`.

## Accessibility

- A real disclosure: `aria-expanded` and `aria-controls` wired to the panel, not a
  custom widget that looks like one.
- The trigger's hit area is extended to ~44px while staying visually compact.
- The full trace is reachable by keyboard, and the collapsed summary carries the same
  duration a sighted user sees.
- Under `prefers-reduced-motion` the step fades and the expand transition are both
  dropped. Nothing is lost — the information was never carried by the motion.

## When not to use

The agent's *activity state* is `Agent Presence`. The full historical record across a
whole turn is `Chain-of-Thought Timeline`. A collapsed "why this?" over an
already-finished value is `AI Context Surface`. And show reasoning **summaries** where
the provider exposes them — raw private chain-of-thought shouldn't be presented to end
users as fact.

## Why it works this way

The component's thesis is the fold-away on completion, not the ticker. Reasoning text is long, low-value-per-token, and usually not what the user wants to read, which creates a bind: showing all of it buries the answer, showing none of it is the black box that destroys trust. Collapsing to a measured 'Thought for 12s' resolves both — the duration answers 'was this worth waiting for' better than any amount of reasoning text, and the disclosure keeps the trace available for anyone who actually wants it. Scroll anchoring is implemented as a correctness requirement rather than a nicety: the component tracks distance-from-end on scroll and only follows new content while the reader is within 24px of the bottom, because auto-scrolling someone who has deliberately scrolled up to read something is the most hostile thing a streaming surface can do. That behaviour came from a competitive scan of a peer library's Message Scroller and now applies as a standing requirement to every streaming surface in this system, not as a component of its own. Each step is its own keyed child component so React's reconciliation owns the entrance animation — a step already on screen keeps its DOM node and can never replay its fade however often the parent re-renders, which is the same mechanism Progressive Reveal uses and which a timer-based approach gets wrong on the first re-render. `steps` is an array rather than a raw accumulating string so the component never has to guess where one thought ends.

---

Follow the PixelDosa UI rules when building with this component: https://pixeldosa.akshayjayan.com/llms.txt

---

# Response Feedback

> Thumbs with a reason that goes somewhere, and a confirmation that says where.

```bash
npx shadcn@latest add @pixeldosa/response-feedback
```

**Before you use it:** Requires `cn` at `@/lib/utils`. Route `onSubmit` somewhere a person actually reads.

## Usage

```tsx
"use client";

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

<ResponseFeedback
  destination="the team that trains this assistant"
  reasons={[
    { id: "wrong", label: "Something is wrong" },
    { id: "source", label: "Wrong or missing source" },
  ]}
  onSubmit={(feedback) => report(feedback)}
/>
```

## Why it exists

A bare thumbs-down tells a team that something was wrong and nothing about what. Asking
for the reason costs the user two seconds and turns a shrug into something a team can act
on.

## Features

- **A thumbs up sends on its own.** Praise shouldn't cost a form. `askOnUp` changes that
  when you want it.
- **Reasons are multi-select**, in your users' words, because an answer is usually wrong
  in more than one way.
- **The comment is optional**, and an empty one is never sent as feedback.
- **The confirmation names the destination.** "Thanks, that goes to the team that trains
  this assistant."
- **No double submits.** The controls are replaced by the confirmation.

## Variants

### Ready

### Already sent

## Props

| Prop | Type | Notes |
| --- | --- | --- |
| `onSubmit` | `(submission) => void` | Required. `{ verdict, reasonIds, comment? }`. |
| `reasons` | `{ id, label }[]` | Yours. A default set ships. |
| `askOnUp` | `boolean` | Ask for reasons after a thumbs up too. Defaults to `false`. |
| `destination` | `string` | Where the feedback goes, named in the confirmation. |
| `submitted` | `boolean` | Start in the confirmed state. |
| `label` | `string` | Defaults to `"Was this answer useful?"`. |

## Accessibility

- The thumbs are a labelled group of toggle buttons with `aria-pressed`.
- Reasons are real checkboxes inside a `fieldset` with a legend; the chips are their
  labels, so the whole chip is a hit target.
- The comment has a visible label.

## When not to use

- **As the only way to report harm.** Anything unsafe needs a route a person reads, with a
  way to follow up.
- **As a rating that changes the answer.** If a thumbs-down should trigger a retry, say so
  and use `Response Versions`.
- **For support.** A ticket has a conversation; this doesn't.

## Why it works this way

The asymmetry between up and down is the design: a thumbs up submits immediately and a thumbs down opens the reason panel, because the useful signal is concentrated in what went wrong and a form after praise costs goodwill for data nobody reads. Reasons are multi-select rather than a single choice, since an answer is usually wrong in more than one way, and they arrive as ids so the caller can route and aggregate them without parsing labels. The comment stays optional and is trimmed to undefined when empty, so a submission never carries a whitespace string that looks like feedback in a dashboard. After sending, the component collapses to a single sentence naming the destination instead of leaving the controls in place, which prevents the double-submit that turns one opinion into three.

---

Follow the PixelDosa UI rules when building with this component: https://pixeldosa.akshayjayan.com/llms.txt

---

# Response Versions

> Every answer the agent gave, kept — step between them, compare two, keep the one you want.

```bash
npx shadcn@latest add @pixeldosa/response-versions
```

**Before you use it:** Requires `cn` at `@/lib/utils`. Append a new version on regenerate; never replace one.

## Usage

```tsx
"use client";

import { ResponseVersions } from "@/components/ui/response-versions";

<ResponseVersions
  versions={versions}
  activeId={activeId}
  onActiveChange={setActiveId}
  onRegenerate={regenerate}
  onKeep={keep}
  busy={regenerating}
/>
```

Append a version when you regenerate. Never replace one.

## Why it exists

Regenerating is the most common thing people do with an AI answer, and in most products it
destroys the previous one. That makes a better answer a gamble, and it's why people paste
answers into a notes app before trying again.

## Features

- **Nothing is lost.** Regenerating appends. The count says how many you have.
- **Compare with the previous one**, side by side, with the current version outlined.
- **Keep one** and hand it back to your app as the answer.
- **The old answer stays readable** while a new one is being written. The busy state lives
  in the button, not over the text.
- **Still**, except a single fade when you switch versions.

## Examples

Regenerating appends, so the list is the history:

```tsx
const regenerate = async () => {
  setBusy(true);
  const next = await model.regenerate();
  setVersions((previous) => [...previous, { id: next.id, label: "Another try", content: next.text }]);
  setActiveId(next.id);
  setBusy(false);
};
```

Inside a chat turn, under the answer:

```tsx
<Message role="assistant" author="Assistant">
  <MessageContent>
    <ResponseVersions versions={turn.versions} activeId={turn.activeId} onActiveChange={choose} />
  </MessageContent>
</Message>
```

## Props

| Prop | Type | Notes |
| --- | --- | --- |
| `versions` | `{ id, content, label?, time? }[]` | Required, oldest first. `time` is formatted by you. |
| `activeId` | `string` | Required. |
| `onActiveChange` | `(id: string) => void` | Required. |
| `onRegenerate` | `() => void` | Adds the Regenerate button. |
| `onKeep` | `(id: string) => void` | Adds "Keep this one". |
| `busy` | `boolean` | True while a new version is being produced. |
| `label` | `string` | Names the control group. Defaults to `"Answer versions"`. |

## Accessibility

- The controls are a labelled group; the arrows are named "Previous version" and "Next
  version" and disable at the ends.
- The position ("Showing version 2 of 3") is announced, not the content, so switching
  doesn't re-read the whole answer.
- In compare mode each side is a labelled region, and the current one says "showing now"
  rather than relying on the outline.

## When not to use

- **A document's revision history.** This is for a handful of attempts at one answer.
- **Comparing two arbitrary versions.** Comparison is deliberately current-versus-previous;
  the question people actually ask is "is this better than the last try?".

## Why it works this way

Versions are a caller-owned array and the component holds only the compare toggle, because the history has to outlive this component's mount — a version list kept in local state would be lost by any parent re-mount, which is exactly the loss the component exists to prevent. Comparison is deliberately limited to the current version and the one immediately before it: an arbitrary two-version picker doubles the controls for a case nobody had, and the common question is always "is this better than the last try?". The compare toggle resets itself when there is no previous version, so a shrinking list cannot leave the component in a state it cannot render. The announcement says which version is showing rather than the content, so switching versions with a screen reader gives position, not a re-read of the whole answer.

---

Follow the PixelDosa UI rules when building with this component: https://pixeldosa.akshayjayan.com/llms.txt

---

# Run Inbox

> Every agent run in one place, with the ones that need a person at the top.

```bash
npx shadcn@latest add @pixeldosa/run-inbox
```

**Before you use it:** Requires `cn` at `@/lib/utils`. Phrase `note` as the thing a person needs to decide or know, not as a status code.

## Usage

```tsx
"use client";

import { RunInbox } from "@/components/ui/run-inbox";

<RunInbox runs={runs} onOpen={open} onStop={stop} />
```

## Why it exists

The way people work with background agents now is: give it a job, close the laptop, come
back later. An inbox is the familiar shape for that — and its familiar failure is strict
chronology, where the run that has been waiting three hours for an answer sits below the
one that finished a minute ago.

## Features

- **Grouped by what the run needs**, not when it happened. Waiting on you comes first,
  whatever its age, then problems, then finished, then scheduled.
- **Counts per group**, so the size of the pile is visible before you scroll.
- **Only running rows move.** Rows waiting on you hold still, in the waiting colour.
- **Stop appears only on running rows**, so it can't be aimed at a finished one.
- **Unread changes weight** and is announced, rather than creating a separate "new"
  section.

## Props

| Prop | Type | Notes |
| --- | --- | --- |
| `runs` | `{ id, title, state, agent?, note?, time?, unread? }[]` | `state` is `needsYou`, `running`, `scheduled`, `done` or `failed`. `time` is formatted by you. |
| `onOpen` | `(id: string) => void` | Required. |
| `onStop` | `(id: string) => void` | Shown on running rows. |
| `emptyLabel` | `string` | Shown when there are no runs. |
| `title` | `string` | Defaults to `"Runs"`. |
| `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | Defaults to `3`. |

## Accessibility

- A labelled `<section>`; each group is a heading with its count.
- Each run's title is a button, so keyboard users move through runs, not decorations.
- "Not opened yet" is announced for unread rows rather than shown only as weight.
- The running dot's pulse stops under `prefers-reduced-motion`.

## When not to use

- **The steps inside one run:** use `Agent Plan` with statuses.
- **A notification feed:** this is a work queue, not an activity stream.
- **Hundreds of runs:** at that size you need search and filters around it.

## Why it works this way

Grouping by state rather than sorting by time is the whole component, and it is why this is not a generic list: the research on agent management interfaces names the inbox's scaling problem exactly, and a pile ordered by recency buries the only rows that block progress. Counts sit on the group headers instead of a single unread badge, because 'four waiting on you' and 'four finished' are different feelings and one number cannot carry both. `unread` only changes weight and adds a screen-reader phrase rather than driving a separate 'new' section, since a run's state matters more than whether it has been opened. Stop appears only on running rows, so the control cannot be aimed at a run that has already ended.

---

Follow the PixelDosa UI rules when building with this component: https://pixeldosa.akshayjayan.com/llms.txt

---

# Select

> A choice from a short, known list, with the open list drawn in the system's own surface. A form field, or a compact pill for toolbars.

```bash
npx shadcn@latest add @pixeldosa/select
```

**Before you use it:** Requires `cn` at `@/lib/utils`. Option values must be non-empty strings. A `prefix` is hidden from screen readers, so name the control with `aria-label` or a label.

## Usage

```tsx
import { Select } from "@/components/ui/select";

export function ModelPicker({ model, onModelChange }: Props) {
  return (
    <Select
      aria-label="Model"
      value={model}
      onValueChange={onModelChange}
      options={[
        { value: "fast", label: "Fast: drafts in seconds" },
        { value: "balanced", label: "Balanced" },
        { value: "careful", label: "Careful: checks its sources" },
      ]}
    />
  );
}
```

`options` takes plain strings when what's shown is what's stored, or `{ value, label }`
when they differ. Pass `value` with `onValueChange` when you own the state, or
`defaultValue` when you don't.

## Features

- **The list is drawn by the system.** It opens in the same popover surface as every
  other overlay, in both themes, instead of an OS menu in the OS's colours and fonts.
- **Native behaviour kept.** Space, Enter and the arrow keys open it, arrows move,
  typing jumps to a match, and Escape or Tab close it with focus back on the trigger.
- **Sized to the choice.** The trigger is as wide as its current value, not its longest
  option, so a row of pills stays compact.
- **Works in forms.** Inside `FieldControl` it receives `id`, `aria-invalid` and
  `aria-describedby` like any input. With `name`, a hidden native select submits the
  value with the form.
- **Touch-sized options.** Rows are 32px for a mouse and 44px on touch screens.

## Variants

### Field

The default. It sits in a form beside inputs, at Field height, or 32px with `size="sm"`.

### Pill

A compact chip for toolbars and composers. `prefix` shows a label before the value; it's
visual only, so name the control with `aria-label`.

### Placeholder and disabled options

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `options` | `(string \| { value, label?, disabled? })[]` | — | Required. Values must be non-empty strings. |
| `value` / `onValueChange` | `string` / `(value: string) => void` | — | The selected value when you own the state, and the callback with each pick. |
| `defaultValue` | `string` | — | The starting value when the component owns the state. |
| `placeholder` | `string` | — | Shown, muted, while nothing is selected. |
| `variant` | `"field" \| "pill"` | `"field"` | A form control, or a compact chip for toolbars. |
| `size` | `"sm" \| "default"` | `"default"` | Height of the field variant: Field height, or 32px. |
| `prefix` | `string` | — | Visual label before the value, such as `Tone:`. Hidden from screen readers. |
| `name` / `required` | `string` / `boolean` | — | Submit the value with a form, and require a choice first. |
| `disabled` | `boolean` | `false` | The whole control can't be opened. |

Other props, such as `id`, `aria-label` and `className`, go to the trigger button.

## Accessibility

- The trigger is a combobox over a listbox, so a screen reader announces its name, its
  role and the current value, and each option's selected state.
- Name it with `aria-label`, a `<label htmlFor>` pointing at its `id`, or `FieldLabel`
  inside a `Field`. A `prefix` is hidden from screen readers so it isn't read twice.
- Focus returns to the trigger when the list closes, by a pick, Escape or Tab.
- The pill's hit area reaches 44px tall without making the chip bigger.

## When not to use

Searching a long or remote list is `Command Menu`. Two or three choices that should
stay visible side by side are better as buttons. A yes or no setting is a toggle, not a
select.

## Why it works this way

Replaces the native selects the system used to use. A native select was the right default for input methods and phones, but its open list is an OS menu in the OS's colours and fonts, and it was the one surface the system couldn't style, which showed most in the dark theme. Radix Select keeps what native gave and draws the list itself: Space, Enter and arrows open it, arrows move, typeahead jumps, Escape and Tab close it with focus back on the trigger, and the trigger is a combobox over a listbox, so screen readers announce the label, the role and the current value. The API is data rather than composition (`options`, `value`, `onValueChange`), so a model rendering from the catalogue can drive it with plain JSON, and so both of the system's call sites, Intent Preview's corrections and Prompt Composer's pills, are one element each. The trigger sizes to its current value rather than the longest option, which is what Prompt Composer's pills had to fake with a transparent native select laid over a label. The pill's hit area stretches to 44px vertically because pills sit in a row; the field variant doesn't, because stacked fields would overlap. Options are 32px rows for a mouse and 44px on coarse pointers. With `name` set, Radix renders a hidden native select, so plain form submission keeps working.

---

Follow the PixelDosa UI rules when building with this component: https://pixeldosa.akshayjayan.com/llms.txt

---

# Selection Actions

> A floating, selection-triggered toolbar for AI actions — explain, rewrite (reviewed via Diff Accept), translate, classify, extract.

```bash
npx shadcn@latest add @pixeldosa/selection-actions
```

Composes (installed automatically): `diff-accept`, `confidence-meter`.

**Before you use it:** Requires `cn` at `@/lib/utils` and the `diff-accept` primitive at `@/components/ui/diff-accept` (installed automatically as a registry dependency), used to render the 'replacement' result kind. Renders via a React portal to document.body with `position: fixed`, so it is not clipped by an `overflow: hidden` ancestor. Keyboard-only users generally cannot create an arbitrary text selection in static, non-editable content — a platform-level limitation this component cannot fix; the guarantee it makes is that once any selection exists, the toolbar itself is fully keyboard-operable.

## Usage

```tsx
"use client";

import * as React from "react";
import {
  SelectionActions,
  type SelectionAction,
  type SelectionActionResult,
} from "@/components/ui/selection-actions";

const actions: SelectionAction[] = [
  { id: "explain", label: "Explain", icon: <ExplainIcon /> },
  { id: "rewrite", label: "Rewrite", icon: <RewriteIcon /> },
];

async function handleAction(
  actionId: string,
  selectedText: string,
  signal: AbortSignal
): Promise<SelectionActionResult> {
  const response = await callYourModel(actionId, selectedText, signal);
  return response; // shaped as one of the SelectionActionResult kinds below
}

export function Article({ text }: { text: string }) {
  const containerRef = React.useRef<HTMLDivElement>(null);
  const [content, setContent] = React.useState(text);

return (
    <>
      <div ref={containerRef}>{content}</div>
      <SelectionActions
        containerRef={containerRef}
        actions={actions}
        onAction={handleAction}
        onReplace={(merged, original) => setContent((c) => c.replace(original, merged))}
      />
    </>
  );
}
```

Only text selected inside `containerRef` triggers the toolbar — selections elsewhere
on the page are ignored, so multiple independent text regions don't fight over which
selection is active.

### Result shapes

`onAction` must resolve to one of four shapes, each rendered differently:

```ts
type SelectionActionResult =
  | { kind: "replacement"; value: string }   // rendered via Diff Accept
  | { kind: "text"; value: string }          // prose, e.g. Explain/Translate
  | { kind: "classification"; label: string; confidence?: "low" | "medium" | "high" }
  | { kind: "list"; items: string[] };        // e.g. Extract
```

`replacement` is the only kind that can call `onReplace` — it renders through `Diff
Accept` internally, so the user reviews and explicitly accepts before anything
changes. The other three kinds only display information; they never touch the
consumer's content.

## Features

- **Scoped to one container.** Only selections inside `containerRef` raise the toolbar,
  so independent text regions never fight over which selection is active.
- **Four result shapes, one component** — `replacement`, `text`, `classification` and
  `list` each render appropriately, so Explain, Rewrite, Translate, Classify and Extract
  all share a single surface.
- **Only `replacement` can change your content**, and it does so through `Diff Accept`
  rather than a second accept/reject implementation — composing an existing trust
  primitive instead of reinventing it (DESIGN.md §3.6).
- **The other three kinds are read-only** by construction: they display and never call
  `onReplace`.
- **Aborts on demand** — `onAction` receives an `AbortSignal`, so a superseded or
  dismissed action cancels the model call rather than leaking it.
- **Honest about a platform limit** it can't fix — see Accessibility.

## Examples

A read-only action set, where nothing the model returns can modify the document —
useful for reference material that must stay verbatim:

```tsx
const actions: SelectionAction[] = [
  { id: "explain", label: "Explain", icon: <ExplainIcon /> },
  { id: "translate", label: "Translate", icon: <TranslateIcon /> },
];

<SelectionActions containerRef={containerRef} actions={actions} onAction={handleAction} />
```

Omitting `onReplace` entirely is the enforcement: with no handler, an accepted
`replacement` has nowhere to land.

Returning a classification rather than prose — the confidence tier flows straight into
`Confidence Meter`'s presentation:

```ts
async function handleAction(actionId, selectedText, signal) {
  if (actionId === "classify") {
    const { label, tier } = await classify(selectedText, signal);
    return { kind: "classification", label, confidence: tier };
  }
  return { kind: "text", value: await explain(selectedText, signal) };
}
```

Extraction, rendered as a list:

```ts
return { kind: "list", items: ["hello@acme.com", "+1 555 0123"] };
```

Making the toolbar less eager on long selections by waiting longer after the selection
settles:

```tsx
<SelectionActions
  containerRef={containerRef}
  actions={actions}
  onAction={handleAction}
  settleMs={400}
/>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `containerRef` | `React.RefObject<HTMLElement \| null>` | — | Required. Scopes selection detection to this element. |
| `actions` | `SelectionAction[]` | — | Required. `{ id, label, icon }` per action. |
| `onAction` | `(actionId, selectedText, signal) => Promise<SelectionActionResult>` | — | Required. |
| `onReplace` | `(mergedValue: string, originalSelectedText: string) => void` | — | Fires only for an accepted `replacement` result. |
| `settleMs` | `number` | `200` | Debounce after the selection stops changing before the toolbar appears. |

## Accessibility

- The toolbar is a real `role="toolbar"` of `<button>` elements in natural tab order.
- Result state changes are announced; confidence is always shown as text, never colour
  alone.
- **A real limit, not glossed over:** keyboard-only users generally cannot create an
  arbitrary text selection in static, non-editable content at all — this is a
  platform-level gap, not something a floating toolbar can fix. What this component
  does guarantee: once any selection exists (mouse, platform accessibility tooling, or
  keyboard inside an editable context where keyboard selection works), the toolbar
  itself is fully keyboard-operable.
- Escape dismisses the toolbar or result from anywhere within it; clicking outside
  does the same.
- Under `prefers-reduced-motion`, the toolbar's entrance is instant rather than
  animated, with no loss of legibility.

## When not to use

A whole-field or whole-document action, with no selection involved, is `Smart Field`
(one field) or `Diff Accept` directly (a rewrite already proposed elsewhere) — not
this component.

## Why it works this way

Composes Diff Accept for the 'replacement' result kind (Rewrite) rather than reimplementing accept/reject a second time — Rewrite is exactly the 'AI proposes replacement text, human reviews' problem Diff Accept already solves, and the two components sharing one review UI keeps the whole AI tier consistent instead of each component inventing its own version of the same interaction. Selection detection listens to document-level `selectionchange`, filtered to whether the selection's anchor node falls inside `containerRef`, debounced (default 200ms) so the toolbar appears once the selection has settled rather than jittering while the user is still dragging or extending with the keyboard — one mechanism covers both input methods, since `selectionchange` fires for either. The toolbar's root uses `onMouseDown` with `preventDefault` — the standard rich-text-editor-toolbar trick — because without it, focusing a toolbar button would collapse the browser's live selection before the click handler ever runs, since focusing an element outside the current selection normally clears it. `onReplace` deliberately takes the original selected text as a second argument rather than assuming a plain string content model on the component's own side: this component cannot know whether the consumer's content is a plain string, a contentEditable region, or a structured rich-text document, so it hands back enough context (the exact original substring) for a plain-string consumer to splice correctly via `content.replace(original, merged)`, while a richer content model would use its own document API and ignore the second argument.

---

Follow the PixelDosa UI rules when building with this component: https://pixeldosa.akshayjayan.com/llms.txt

---

# Smart Field

> An AI-proposed value for a single field — confidence, source, explicit accept/reject, and one-step undo before it ever becomes real data.

```bash
npx shadcn@latest add @pixeldosa/smart-field
```

Composes (installed automatically): `field`, `confidence-meter`.

**Before you use it:** value/onValueChange are required — this is a controlled component only, matching ghost-input's contract. fetchProposal must resolve to the FULL proposed value (not a delta) plus optional confidence/provenance; return null/undefined for 'no proposal available' rather than throwing. triggerIcon is required with no bundled default — pass any size-4 SVG/icon element. autoPropose only fires once, on mount, and only when value is empty, so it can never silently overwrite existing data. Drops into <FieldControl> directly since id/aria-invalid/aria-describedby/ref all forward to the underlying <input>.

## Usage

```tsx
"use client";

import * as React from "react";
import { SmartField, type SmartFieldProposal } from "@/components/ui/smart-field";

async function fetchProposal(
  currentValue: string,
  signal: AbortSignal
): Promise<SmartFieldProposal | null> {
  const response = await fetch(`/api/enrich?value=${currentValue}`, { signal });
  if (!response.ok) return null;
  return response.json(); // { value, confidence, provenance }
}

export function CompanyField() {
  const [value, setValue] = React.useState("");

return (
    <SmartField
      id="company"
      value={value}
      onValueChange={setValue}
      fetchProposal={fetchProposal}
      triggerIcon={<SparkleIcon />}
      triggerLabel="Suggest company name"
    />
  );
}
```

The field's value never changes until the proposal is explicitly accepted. Typing
manually at any point — while a fetch is in flight, or once a proposal is shown but not
yet accepted — cancels the request or dismisses the proposal, since manual input always
wins over an AI suggestion.

### Confidence and provenance

```tsx
return {
  value: "Acme Robotics, Inc.",
  confidence: "medium",
  provenance: "acme-robotics.com",
};
```

`confidence` is a three-tier enum (`low` / `medium` / `high`), not a raw percentage —
a fabricated number would claim precision the model doesn't actually have. `provenance`
is free text rendered as `via {provenance}`; omit it if you have nothing honest to show.

### Auto-propose on an empty field

```tsx
<SmartField autoPropose value={value} onValueChange={setValue} fetchProposal={fetchProposal} triggerIcon={<SparkleIcon />} />
```

Fires once, on mount, and only when `value` is empty — it can never silently
reconsider a value that's already there. Off by default; most fields should wait for an
explicit click.

## Features

- **Nothing commits silently.** The field's value never changes until the proposal is
  explicitly accepted, and a one-step Undo stays available afterwards (DESIGN.md §3.7).
- **Manual input always wins.** Typing at any point — mid-fetch, or with a proposal on
  screen — cancels the request or dismisses the proposal, so the AI can never overwrite
  what someone is actively doing.
- **Confidence as a three-tier enum, not a percentage**, shown as text with a
  supplementary bar rather than a colour-coded badge.
- **Provenance next to the proposal**, so a value arrives with its evidence instead of
  asking to be trusted on its own.
- **Auto-propose is opt-in and fires once**, only on mount and only into an empty
  field — it can never silently reconsider a value that's already there.
- **Drops into `<FieldControl>` unchanged**, forwarding `id`, `aria-invalid` and
  `aria-describedby` to the real `<input>`.

## Examples

Auto-proposing into an empty field, for a form where the enrichment is the whole point
and waiting for a click is pure friction:

```tsx
<SmartField
  autoPropose
  value={value}
  onValueChange={setValue}
  fetchProposal={fetchProposal}
  triggerIcon={<SparkleIcon />}
/>
```

Reacting to an acceptance — the honest place to measure whether proposals are actually
good, rather than counting how often they were merely shown:

```tsx
<SmartField
  value={value}
  onValueChange={setValue}
  fetchProposal={fetchProposal}
  triggerIcon={<SparkleIcon />}
  onAcceptProposal={(value, proposal) =>
    analytics.track("proposal_accepted", { confidence: proposal.confidence })
  }
/>
```

Returning `null` is a first-class answer — say nothing rather than propose noise:

```tsx
async function fetchProposal(currentValue, signal) {
  const match = await lookup(currentValue, signal);
  if (!match || match.score < 0.6) return null;
  return { value: match.name, confidence: match.tier, provenance: match.domain };
}
```

Composed inside a `Field`, where label, description and error wiring come for free:

```tsx
<Field invalid={Boolean(error)}>
  <FieldLabel>Company</FieldLabel>
  <FieldControl>
    <SmartField
      value={value}
      onValueChange={setValue}
      fetchProposal={fetchProposal}
      triggerIcon={<SparkleIcon />}
    />
  </FieldControl>
  <FieldError>{error}</FieldError>
</Field>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` | — | Required. Controlled field value. |
| `onValueChange` | `(value: string) => void` | — | Required. |
| `fetchProposal` | `(currentValue: string, signal: AbortSignal) => Promise<SmartFieldProposal \| null \| undefined>` | — | Required. Return `null`/`undefined` for "no proposal." |
| `onAcceptProposal` | `(value: string, proposal: SmartFieldProposal) => void` | — | Fires after the user accepts. |
| `triggerIcon` | `React.ReactNode` | — | Required. No bundled icon set — pass a `size-4` icon. |
| `triggerLabel` | `string` | `"Suggest a value with AI"` | Accessible label for the trigger button. |
| `autoPropose` | `boolean` | `false` | Fetch once on mount if `value` is empty. |
| `undoWindowMs` | `number` | `6000` | How long the Undo affordance stays visible after accepting. |

`SmartFieldProposal` is `{ value: string; confidence?: "low" | "medium" | "high";
provenance?: string }`.

## Accessibility

- Every state change (proposal arrived, accepted, undone) is announced via
  `aria-live="polite"`.
- Confidence is communicated as text, never colour alone — the tiered bar indicator
  next to the label is supplementary, not the only signal.
- Trigger, Accept, Reject and Undo are all real `<button>` elements, keyboard-reachable
  by default, with a minimum 44×44px hit target.
- Drops into `<FieldControl>` directly — `id`, `aria-invalid` and `aria-describedby`
  all forward to the underlying `<input>`.
- Under `prefers-reduced-motion`, the proposal panel's expand/collapse and every colour
  transition lose their animation but not the underlying state change.

## When not to use

Inline predictive continuation while typing is `Ghost Input`, not this — Smart Field
proposes a complete replacement value reviewed before commit, not a tail appended as
you type. Multi-field or long-text diffing belongs to `Diff Accept`; a consequential or
risky action needing full review belongs to `AI Approval Gate`.

## Why it works this way

Mirrors ghost-input's contract shape (value/onValueChange controlled-only, a fetchX behaviour injected by the consumer, an AbortSignal for cancellation) deliberately, so the AI tier reads as one consistent family rather than each component inventing its own pattern — the two differ only in what they return: a plain continuation string for ghost-input versus a structured { value, confidence, provenance } proposal here, because a complete replacement value needs that context attached and a continuation tail does not. Confidence rendering composes the shared `confidence-meter` primitive (extracted after Selection Actions needed the identical tiered indicator) rather than hand-rolling its own bars a second time — a three-tier enum (low/medium/high), not a raw number, because a fabricated percentage would claim precision the underlying model doesn't actually have, and because the system has no colour scale to spend on a red/yellow/green treatment anyway. autoPropose is opt-in and gated to empty fields only, adopted directly from CRM-enrichment research (Clay/HubSpot/Attio): confidence gates whether a proposal is allowed to overwrite existing data, so the safest default auto-behaviour is 'only ever fill a blank,' never 'silently reconsider what's already there.' Manual typing at any point cancels an in-flight fetch or dismisses a shown-but-unaccepted proposal, reusing ghost-input's staleness philosophy: a suggestion answering a question the field no longer asks is worse than no suggestion. The proposal panel animates open/closed via a CSS grid-template-rows trick (0fr to 1fr) rather than measuring and animating an explicit pixel height, which is the standard token-free way to animate a height that depends on variable content without a ResizeObserver.

---

Follow the PixelDosa UI rules when building with this component: https://pixeldosa.akshayjayan.com/llms.txt

---

# Suggestions

> Follow-up questions after an answer, where it's always clear whether a tap fills the composer or sends right away.

```bash
npx shadcn@latest add @pixeldosa/suggestions
```

**Before you use it:** Requires `cn` at `@/lib/utils`. Default to `mode="fill"`. Use `send` only when the suggestions are exactly what the user would type. Pass `streaming` from the message status.

## Usage

```tsx
"use client";

import { Suggestions } from "@/components/ui/suggestions";

<Suggestions
  items={["Which teams didn't finish setup?", "Draft an onboarding email"]}
  streaming={message.status === "streaming"}
  onSelect={(prompt) => composer.fill(prompt)}
/>
```

## Why it exists

Suggestion chips usually hide the one thing that matters: **does tapping this send a
message?** Sending words someone didn't write can't be undone in a conversation. Here the
mode is a choice you make, and it's visible.

## Features

- **Fill or send, visibly.** A pencil means the text goes into the composer to edit. An arrow means it's asked immediately.
  Screen readers hear "Edit before asking:" or "Ask:".
- **Safe by default.** `mode="fill"` unless you choose otherwise.
- **Not mid-stream.** Hidden while the answer is still arriving.
- **Chips or list.** Wrapping pills for short prompts, full-width rows for longer questions.
- **Label and prompt can differ.** Show "Compare with July" and ask the full question.
- **One tab stop.** Arrow keys, Home and End move between suggestions.

## Examples

Send mode, for prompts that are exactly what the user would type:

```tsx
<Suggestions mode="send" layout="list" items={followUps} onSelect={(prompt) => send(prompt)} />
```

A short label that asks a fuller question:

```tsx
<Suggestions
  items={[{ id: "july", label: "Compare with July", prompt: "Compare August churn with July, by plan." }]}
  onSelect={fill}
/>
```

## Props

| Prop | Type | Description |
| --- | --- | --- |
| `items` | `(string \| { id, label, prompt? })[]` | Required. |
| `onSelect` | `(prompt, item) => void` | Required. |
| `mode` | `"fill" \| "send"` | Defaults to `"fill"`. |
| `streaming` | `boolean` | Hides the suggestions. |
| `layout` | `"chips" \| "list"` | Defaults to `"chips"`. |
| `label` | `string` | Group name. Defaults to `"Suggested follow-ups"`. |

## Accessibility

- A named group with a single tab stop and arrow-key movement.
- Each item's name says what a tap does.
- List rows are 44px tall, and chips extend their hit area vertically.

## When not to use

This isn't autocomplete. For completing text as someone types, use `Ghost Input`. For suggestions
inside the composer before the first message, use `Prompt Composer`'s `suggestions`.

## Why it works this way

Most suggestion chips hide their most important property: whether tapping one sends a message. Sending words the user didn't write can't be taken back in a conversation, so the component makes mode explicit in three places: the trailing glyph (pencil for fill, arrow for send), the accessible name ('Edit before asking:' vs 'Ask:'), and the default, which is the safer `fill`. Items accept a separate `prompt`, so a short visible label can expand into a fuller question. Suggestions render nothing while `streaming`, because a follow-up to an unfinished answer is premature and often wrong once the answer completes. Keyboard behaviour follows the toolbar pattern already used in AI Action Toolbar: one tab stop with roving tabindex, arrows in both axes (so it works for wrapping chips and stacked lists), and Home and End. The active index resets if the list shrinks. Chips extend their hit area vertically with a transparent pseudo-element, and list rows are 44px tall.

---

Follow the PixelDosa UI rules when building with this component: https://pixeldosa.akshayjayan.com/llms.txt

---

# Tool Call Card

> What the agent actually did — read, searched, fetched, wrote — as a record beside what it says, so retrieved knowledge looks different from assumed knowledge.

```bash
npx shadcn@latest add @pixeldosa/tool-call-card
```

**Before you use it:** Requires `cn` at `@/lib/utils`. Map each tool your agent exposes to a `kind`, and override `effect` for tools whose side effects the kind doesn't imply (e.g. a `run` that is read-only). Show the group next to the answer it supports, not in a separate debug panel.

## Usage

```tsx
"use client";

import { ToolCallCard, ToolCallGroup } from "@/components/ui/tool-call-card";

<ToolCallGroup calls={run.toolCalls} />
```

## Why it exists

"The config sets a 30s timeout" reads the same whether the agent opened the file or
guessed. A record of the calls next to the answer shows which it was. It also shows
what didn't work: a failed fetch sits right beside an answer that skipped those docs.

## Features

- **A sentence, not a log line.** Verb, then the exact target in monospace:
  "Read `src/config.ts`". Arguments and result are one click away.
- **Acting stands out from looking.** Read-only calls stay quiet. Calls that made
  changes or reached outside the app are labelled, because those are what a reviewer
  looks for.
- **One line for a whole run.** `ToolCallGroup` reads "Read 2 files, searched once, wrote
  1 file", with "1 call made changes" and "1 failed" beside it. While a call runs, that call replaces the tally.
- **Honest counts.** Only finished calls count as done. Failures and blocked calls are
  reported separately.
- **Evidence can't swamp the page.** Results are height-capped with their own scroll.

## Effects

| `effect` | Default for | Shown as |
| --- | --- | --- |
| `read-only` | `read`, `search`, `fetch` | nothing extra |
| `changes` | `write`, `run` | "Made changes" |
| `external` | `call` | "Outside this app" |

Override when the kind lies: a `run` of `git status` is read-only.

## Examples

Mapping tool events, whatever your agent runtime:

```tsx
const kindFor = { read_file: "read", grep: "search", web_fetch: "fetch", edit_file: "write", bash: "run" };

const calls = events.map((event) => ({
  id: event.id,
  kind: kindFor[event.tool] ?? "call",
  name: event.tool,
  target: event.args.path ?? event.args.query ?? event.args.url ?? event.tool,
  status: event.error ? "failed" : event.result === undefined ? "running" : "done",
  input: event.args,
  output: event.result,
  error: event.error,
}));
```

A call the user's permissions stopped:

```tsx
<ToolCallCard kind="write" target=".env" status="blocked" error="Secrets files are outside this agent's scope." />
```

## Props

### ToolCallCard

| Prop | Type | Description |
| --- | --- | --- |
| `kind` | `"read" \| "search" \| "fetch" \| "write" \| "run" \| "call"` | Required. |
| `target` | `string` | Required. What it touched: path, query, URL, command. |
| `status` | `"running" \| "done" \| "failed" \| "blocked"` | Required. |
| `name` | `string` | The raw tool name. |
| `effect` | `"read-only" \| "changes" \| "external"` | Defaults from `kind`. |
| `input` | `string \| object` | Objects render as formatted JSON. |
| `output` | `ReactNode` | Strings render as a scrollable block. |
| `error` | `string` | Why it failed or was blocked. |
| `durationMs` | `number` | Hidden while running. |
| `defaultOpen` | `boolean` | |

### ToolCallGroup

| Prop | Type | Description |
| --- | --- | --- |
| `calls` | `(ToolCallCardProps & { id })[]` | Required. |
| `defaultOpen` | `boolean` | Collapsed by default. |

## Accessibility

- Summaries are buttons with `aria-expanded`, and details are hidden with `inert` when closed.
- Calls in a group are an ordered list, because the order is part of the record.
- Status is carried by words ("Couldn't fetch", "Not allowed to write"), not only colour.
- The running shimmer falls back to static text under reduced motion.

## When not to use

Don't use it for a debugging console or a raw event log. It's for people reviewing
what an agent did. For the agent's current activity in one line, use `Live Status Line`.
For why it produced an answer, use `AI Context Surface`.

## Why it works this way

Built for a trust gap seen from the model side. An agent's answer blends what it retrieved with what it inferred, and the text alone reads the same either way. A visible record of the calls lets a reader tell 'the config sets a 30s timeout' backed by a read of config.ts from the same sentence with nothing behind it, and it makes failures just as visible: the demo's answer admits the docs fetch failed, and the failed card is right there. Three decisions keep this from becoming a log dump. The summary is a sentence, verb then exact target in monospace, so it scans like prose. Evidence (arguments and result) sits in a disclosure, capped in height with its own scroll so one large result cannot swamp the run. And effect is a first-class prop defaulted from the kind, so the handful of calls that changed something are labelled among the many that only looked. Blocked calls never ran, so they never carry an effect label. The group tallies only finished calls and reports failures separately, so the headline never counts a failed read as a read. Collapsible regions use the house 0fr→1fr grid with overflow-hidden, padding inside the min-h-0 child, and inert while closed.

---

Follow the PixelDosa UI rules when building with this component: https://pixeldosa.akshayjayan.com/llms.txt

---

# Variation Grid

> The results of one prompt — keep the good ones and regenerate only the rest.

```bash
npx shadcn@latest add @pixeldosa/variation-grid
```

**Before you use it:** Requires `cn` at `@/lib/utils`. Render each `preview` yourself: an `img`, a poster frame, a card of text. Set `aspectRatio` to your output's shape so the grid never jumps.

## Usage

```tsx
"use client";

import { VariationGrid } from "@/components/ui/variation-grid";

<VariationGrid
  title="A dark bottle on a stone surface"
  items={results.map((result) => ({
    id: result.id,
    label: result.label,
    status: result.status,
    preview: <img src={result.url} alt="" className="size-full object-cover" />,
  }))}
  keptIds={kept}
  onKeptChange={setKept}
  onRegenerateRest={regenerate}
  regenerateCost="30 credits"
  onUse={insert}
/>
```

## Why it exists

Research on how people use generation tools calls it apple picking: they keep the two
results they like and run the rest again. Almost no tool supports it, so people download
their favourites, re-prompt, and lose track of which was which — paying for the good ones
twice.

## Features

- **Keeping is a state.** Kept results are marked and survive the next regeneration.
- **"Regenerate the other 3"** replaces only what isn't kept, and says so.
- **The price is on the button**, before the click. Unpriced iteration is the loudest
  complaint in this category.
- **Failures are per cell.** One timed-out result shows its own reason and its own Retry;
  the others stay usable.
- **The grid never jumps.** Set `aspectRatio` to your output's shape.
- **Only unfinished cells move.** Kept ones hold still.

## Props

| Prop | Type | Notes |
| --- | --- | --- |
| `items` | `{ id, preview?, label?, status?, note? }[]` | Required. You render the previews. |
| `keptIds` / `onKeptChange` | `string[]` / `(ids) => void` | Required. Caller-owned, so keeping survives a regeneration. |
| `onRegenerateRest` | `(idsToReplace) => void` | Receives exactly the ids being replaced. |
| `regenerateCost` | `string` | Shown beside the button. |
| `onUse` / `useLabel` | `(id) => void` / `string` | Takes one result forward. |
| `onMore` | `(id) => void` | More like this one. |
| `onRetry` | `(id) => void` | Retries a single failed cell. |
| `aspectRatio` | `string` | Defaults to `"1 / 1"`. |
| `title` | `string` | Defaults to `"Results"`. |
| `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | Defaults to `3`. |

## Accessibility

- A labelled `<section>`; the count says how many are kept and how many can be replaced.
- Keep is a toggle button with `aria-pressed` and a label naming the result.
- A failed cell states its reason in text, not only in colour.
- Running cells say "Generating…"; their pulse stops under `prefers-reduced-motion`.

## When not to use

- **A single result:** use `Generation Placeholder` while it renders, then your own frame.
- **A gallery of past work:** this belongs to one prompt.
- **Text alternatives in a chat:** use `Response Versions`.

## Why it works this way

The kept set is caller-owned and passed in, because it has to survive the regeneration that replaces the other cells — holding it internally would lose the user's choices exactly when the component re-renders with new results. `onRegenerateRest` hands back the ids it is replacing rather than a bare signal, so the caller can keep positions stable and never has to diff two arrays to work out what the user meant. A cell that is still running is excluded from the replaceable set, which stops a second click from cancelling work already in flight. Per-cell status rather than a batch status comes from how these pipelines actually fail: partial success is the common case, and a grid that collapses to a single error state throws away results the user already paid for. The regeneration cost is a caller-formatted string on the button because unpriced iteration is the single most common complaint in this category.

---

Follow the PixelDosa UI rules when building with this component: https://pixeldosa.akshayjayan.com/llms.txt

---

# Workflow Stepper

> A compact sequential progress indicator for approval, onboarding, and agent-run workflows.

```bash
npx shadcn@latest add @pixeldosa/workflow-stepper
```

**Before you use it:** Requires `cn` at `@/lib/utils`. Keep each step concise: a short title, optional explanation, and a state that the user can understand in one glance.

## Usage

```tsx
import { WorkflowStepper } from "@/components/ui/workflow-stepper";

const steps = [
  { id: "review", title: "Review intent", description: "Checked the request and goals.", status: "complete" },
  { id: "draft", title: "Draft changes", description: "Preparing the first pass.", status: "current" },
  { id: "approve", title: "Approve and ship", description: "Human signoff before launch.", status: "upcoming" },
];

<WorkflowStepper title="Run progress" steps={steps} />
```

## Why it exists

A person should know where they are without reading an entire document. The stepper answers the three questions that matter in a flow: what has happened, what is happening now, and what remains. It is especially useful for permission gates, onboarding, setup tasks, and agent processes where the work is sequential but still needs to feel lightweight.

## Props

| Prop | Type | Notes |
| --- | --- | --- |
| `steps` | `{ id, title, description?, status?, badge? }[]` | Ordered from first to last. |
| `currentStep` | `number` | Optional 0-based index. If omitted, the component uses the first step marked `current`. |
| `title` | `string` | Optional heading above the list. |
| `showStatus` | `boolean` | Displays a small label for complete/current/next. Default `true`. |
| `size` | `"default" \| "compact"` | Defaults to `"default"`. |

## Accessibility

- Uses a semantic ordered list.
- The current step is visually differentiated with colour and ring contrast.
- Completed steps show a checkmark and text remains legible in both light and dark themes.

## When not to use

- For a timeline of events that happened over time; use an activity trail instead.
- For long-form instructions or nested tasks; a wizard or panel is clearer.
- For a single action or a non-sequential check; a button or status chip is simpler.

## Why it works this way

The component resolves state from the caller's `currentStep` or from the first step marked `current`, then derives the visible badge and connector colours rather than storing duplicated state. That keeps the API small and lets the page remain the source of truth for a live flow while the stepper stays presentational and easy to compose in an approval, onboarding, or agent-run layout. The alternative was a full state machine in the component itself, which would create stale logic when a step was already derived elsewhere in the app.

---

Follow the PixelDosa UI rules when building with this component: https://pixeldosa.akshayjayan.com/llms.txt

---

# Agent Console

> The screen you come back to — what changed while you were away, then every run grouped by what it needs.

```bash
npx shadcn@latest add @pixeldosa/agent-console
```

Composes (installed automatically): `run-inbox`, `agent-plan`, `activity-trail`, `human-handoff`, `agent-schedule`.

**Before you use it:** Requires `cn` at `@/lib/utils`. Write `briefing.nextUp` as the one thing worth doing first, not a summary — it is the sentence that has to survive being read on a phone at a bus stop. Times and counts are formatted by you.

## Usage

```tsx
"use client";

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

<AgentConsole
  briefing={{
    since: "yesterday at 18:00",
    needsYou: 2,
    finished: 1,
    failed: 1,
    nextUp: "Start with the refund — it has been waiting three hours.",
  }}
  runs={runs}
  selectedId={selected}
  onSelect={setSelected}
  detail={detail}
  triggers={schedules}
  onTriggerEnabledChange={toggle}
/>
```

## Why it exists

People hand a job to an agent, close the laptop, and come back later. Two products
shipped a surface for exactly that this year, replacing "the agent's work lives in a chat
thread you have to find" with a place designed to be returned to.

The part still treated as an afterthought is the return itself. Research on agentic
interfaces puts it plainly: the moment someone comes back after four hours is where trust
is won or lost, and it should read as a briefing — what happened, what needs you, what to
do next — rather than a pile the person has to reconstruct that from.

## Features

- **The briefing comes first**, in words: what changed since you were last here, and the
  one thing worth doing first. It turns the waiting colour only when something genuinely
  needs a person.
- **Zero is stated.** "Nothing changed while you were away" is a useful answer; an empty
  space isn't.
- **The inbox groups by need, not time**, so a run that's been waiting three hours can't
  sit below one that finished a minute ago.
- **The detail answers the two real questions:** where did it get to (the plan), and who
  let it do that (the trail, with its authority field).
- **A person being involved comes first.** When a run is waiting for someone, the handoff
  sits above the agent's own account of itself.
- **What runs on its own is on the same screen**, as sentences rather than cron.

## Props

| Prop | Type | Notes |
| --- | --- | --- |
| `briefing` | `{ since?, needsYou, finished, failed, nextUp? }` | The return moment. Counts are numbers; `nextUp` is your sentence. |
| `runs` | `AgentRun[]` | Everything Run Inbox takes. |
| `selectedId` / `onSelect` | `string` / `(id) => void` | `onSelect` required. The matching row is marked with `aria-current`. |
| `detail` | `ConsoleRunDetail \| null` | The selected run: `steps`, `trail`, `handoff`. |
| `onStopRun` / `onStopSelected` | `(id) => void` / `() => void` | |
| `onRetryStep` | `(stepId) => void` | On a failed step. |
| `onUndo` / `onExportTrail` | `(entryId) => void` / `() => void` | On the trail. |
| `onTakeOver` / `onReturnToAgent` | `() => void` | On the handoff. |
| `triggers` / `onTriggerEnabledChange` | `ScheduleTrigger[]` / `(id, enabled) => void` | Leave out to hide the schedule entirely. |
| `detailEmptyLabel` / `inboxEmptyLabel` | `string` | |
| `headingLevel` | `2 \| 3 \| 4` | Defaults to `2`. |

`ConsoleRunDetail` is `{ id, title, steps?, runStatus?, trail?, handoff? }`, where
`handoff` is `{ stage, reason?, context?, person?, waitingFor? }`.

## Accessibility

- One labelled section; every part inside carries its own heading one level below it, so
  the outline never skips.
- The open run is marked with `aria-current` as well as a background, so the pairing
  between list and detail doesn't depend on colour.
- Only genuinely running things animate — a running row's dot, a running step's mark.
  The briefing never animates; a summary that moves reads as still arriving.
- Everything stops under `prefers-reduced-motion`, and each state is also in words.

## When not to use

- **One agent run inside a chat:** use `Thinking Experience`.
- **The steps of a single run, on their own:** `Agent Plan`.
- **A notification feed:** this is a work queue, not an activity stream.

## Notes

Write `nextUp` as the one thing worth doing first, not a summary. It's the sentence that
has to survive being read on a phone at a bus stop.

## Why it works this way

The briefing sits above everything and is written in words rather than badges, because the failure of a returned-to surface is that it hands back a pile and makes the person do the triage that the system already has the data to do. It turns the waiting colour only when something actually needs a person, so the colour means the same thing here as it does on a single approval. Zero is stated rather than hidden: 'Nothing changed while you were away' is a useful answer, and an empty space is not. The two-pane split puts the inbox at a fixed width and the detail fluid, because the detail is where the reading happens; the selected row is marked with `aria-current` as well as a background, so the pairing survives without colour. A person being involved is rendered above the machine's account of itself — the handoff comes before the plan and the trail — since a run waiting on somebody is not primarily a story about what the agent did.

---

Follow the PixelDosa UI rules when building with this component: https://pixeldosa.akshayjayan.com/llms.txt

---

# AI Chat Experience

> A complete assistant screen — conversation, reasoning, tool calls, code, sources, follow-ups and composer — with the orchestration decided for you.

```bash
npx shadcn@latest add @pixeldosa/ai-chat-experience
```

Composes (installed automatically): `message`, `message-scroller`, `prompt-composer`, `suggestions`, `code-block`, `reasoning-stream`, `tool-call-card`, `inline-citations`, `agent-presence`, `ai-action-toolbar`, `agent-figure`.

**Before you use it:** Requires `cn` at `@/lib/utils`. Installs the whole chat stack it composes. Keep `turns` in your state and update the latest assistant turn as your stream reports reasoning, tool calls, text and completion. Pass your markdown renderer as `renderText`.

## Usage

```tsx
"use client";

import { AIChatExperience } from "@/components/blocks/ai-chat-experience";

<AIChatExperience
  className="h-dvh"
  turns={turns}
  onSend={({ text }) => send(text)}
  onStop={abort}
  onRetry={retry}
  onContinue={resume}
  onRegenerate={regenerate}
  renderText={(text) => <Markdown>{text}</Markdown>}
  empty={{ title: "What are we working on?", suggestions: starters }}
/>
```

## Why it exists

Every part of an assistant screen exists as a component. What teams get wrong is how the parts behave
**together**: two spinners at once, reasoning that keeps ticking under the answer, stale
follow-ups from three questions ago, a Stop button that disappears, or a screen reader that
reads every token. This block makes those decisions once.

## What it decides

- **One busy signal at a time.** Agent Presence covers the gap before anything else exists.
  Then the reasoning trace or the running tool call says what's happening, and once the answer
  starts, the message's cursor takes over.
- **Reasoning stops when the answer starts,** whatever the stream says.
- **Send becomes Stop** exactly while the latest answer streams. You can still type the next question.
- **Follow-ups belong to the latest finished answer.** Older ones disappear. In `fill` mode
  a follow-up lands in the composer to edit.
- **Code is safe mid-stream.** Fenced code becomes Code Blocks, and Copy waits for the fence to close.
- **Sources sit under the answer,** or inline if you use `content` with `<Cite>`.
- **Screen readers hear each answer once,** when it finishes.
- **Nothing is thrown away.** Failed and stopped turns keep their text, with Retry or Continue.

## Turn data

Your stream updates the latest assistant turn. Everything is plain data:

```tsx
type ChatTurn = {
  id: string;
  role: "user" | "assistant";
  text?: string;               // fenced code becomes Code Blocks
  content?: ReactNode;         // replaces text, e.g. with <Cite> markup
  status?: "streaming" | "done" | "failed" | "stopped";
  error?: string;
  reasoning?: { steps: string[]; streaming?: boolean; durationMs?: number };
  toolCalls?: ToolCall[];
  sources?: CitationSource[];
  suggestions?: Suggestion[];
};
```

## Examples

Mapping stream events, whatever your runtime:

```tsx
on("reasoning", (step) => patch(id, (t) => ({ reasoning: { steps: [...(t.reasoning?.steps ?? []), step] } })));
on("tool-start", (call) => patch(id, (t) => ({ toolCalls: [...(t.toolCalls ?? []), { ...call, status: "running" }] })));
on("text", (chunk) => patch(id, (t) => ({ text: (t.text ?? "") + chunk })));
on("finish", () => patch(id, { status: "done" }));
on("error", (error) => patch(id, { status: "failed", error: error.message }));
```

With structured controls in the composer:

```tsx
<AIChatExperience
  turns={turns}
  controls={[{ id: "tone", label: "Tone", options: ["Neutral", "Friendly"], defaultValue: "Neutral" }]}
  onSend={({ text, values }) => send(text, values)}
/>
```

## Props

| Prop | Type | Description |
| --- | --- | --- |
| `turns` | `ChatTurn[]` | Required. |
| `onSend` | `({ text, values, attachments }) => void` | Required. |
| `onStop` | `() => void` | Shown as Stop while the latest turn streams. |
| `onRetry` / `onContinue` / `onRegenerate` | `(turnId) => void` | |
| `onApplyCode` | `(code, language) => void \| Promise<void>` | Adds Apply to code blocks. |
| `suggestionMode` | `"fill" \| "send"` | Defaults to `"fill"`. |
| `renderText` | `(text) => ReactNode` | Your markdown renderer. |
| `assistantName` | `string` | Defaults to `"Assistant"`. |
| `empty` | `{ title, description?, suggestions? }` | Shown before the first turn. |
| `controls`, `attachments`, `onAttachFiles`, `onRemoveAttachment`, `placeholder` | | Passed to the composer. |
| `onLoadOlder` | `() => void` | Near the top of the history. |
| `headingLevel` | `2 \| 3 \| 4 \| 5` | Level of the empty-state title and of the Sources headings in answers. Defaults to `2`. |
| `expression` | `"full" \| "subtle" \| "off"` | How much of the agent shows. `full` adds its drawn head as the assistant's avatar, `subtle` shows the head only beside "Thinking", `off` uses dots. Defaults to `"subtle"`. |

## Accessibility

- The screen is a labelled section, and the conversation is a focusable, scrollable region.
- Each turn is an article, and turns are busy while streaming.
- One polite announcement per finished, failed or stopped answer.
- Everything else is inherited from the components it composes.

## When not to use

For one agent run with questions and approvals rather than a conversation, use `Thinking
Experience`. For generating a single artifact, use `Prompt Composer` with the result
shown directly.

## Why it works this way

A Block, so an orchestration rather than new UI: every element is an existing component, and the contribution is the rules for combining them. Busy signals are exclusive. `presenceFor` shows Agent Presence only in the gaps where nothing else reports progress (before reasoning or tools exist, or between the last tool and the first token). A streaming reasoning trace or running tool call already says what is happening, and once text exists the Message's quantized cursor takes over, because two simultaneous 'working' indicators read as noise and make neither trustworthy. Reasoning is forced to stop streaming once answer text arrives, regardless of what the reasoning data says, since a ticking trace under a streaming answer misreports what the model is doing. `busy` derives from the latest assistant turn alone, so Send becomes Stop for exactly that window. The composer is controlled by the block, which lets a `fill` suggestion write into it while the user keeps editing during a stream. Suggestions render only on the latest assistant turn in 'done' status, and older turns' suggestions are hidden, so stale follow-ups never compete with current ones. Text goes through `splitCodeFences`, so an unclosed fence streams as a Code Block. Screen reader announcements are derived by diffing each turn's previous status: a transition out of 'streaming' produces one message (replied with a summary, failed, or stopped) and never a token stream. Turn data is plain objects, so it maps from any runtime (AI SDK, LangGraph, a custom SSE stream) without a dependency.

---

Follow the PixelDosa UI rules when building with this component: https://pixeldosa.akshayjayan.com/llms.txt

---

# AI Form Fill

> An agent filling a form you're already looking at — one request, but every field still reviewed on its own terms.

```bash
npx shadcn@latest add @pixeldosa/ai-form-fill
```

Composes (installed automatically): `smart-field`, `field`, `ai-action-toolbar`, `live-status-line`.

**Before you use it:** Requires `cn` at `@/lib/utils`. Installing this pulls in Smart Field, Field, AI Action Toolbar and Live Status Line, plus Confidence Meter and Agent Presence transitively. Fetch the whole batch once in `onFill` and have each field's `fetchProposal` read from that result — otherwise a five-field form makes five round trips for one user action.

## Usage

```tsx
"use client";

import { AIFormFill } from "@/components/blocks/ai-form-fill";

const batch = React.useRef<Record<string, SmartFieldProposal>>({});

<AIFormFill
  fields={[
    { name: "company", label: "Company", fetchProposal: async () => batch.current.company },
    { name: "industry", label: "Industry", fetchProposal: async () => batch.current.industry },
  ]}
  values={values}
  onValueChange={(name, value) => setValues((v) => ({ ...v, [name]: value }))}
  onFill={async () => { batch.current = await enrich(values); }}
  triggerIcon={<SparkleIcon />}
/>
```

Fetch the whole batch once in `onFill`, then have each field's `fetchProposal` read
from it. Otherwise a five-field form makes five round trips for one user action.

## What it refuses to do

Bulk filling makes an **"Accept all"** button feel obvious. It isn't there, deliberately.

Smart Field exists so a proposed value is reviewed *with its confidence and source*
before it becomes real data. A single click that accepts twelve values across three
different confidence tiers silently discards that. So: **the request is bulk, the
review stays per-field.**

That's the honest reading of "nothing commits silently" — not a convenience compromise.

## Features

- **One request, many proposals.** A single token bump makes every field propose
  together, while each keeps ownership of its own proposal, confidence, undo window and
  in-flight request.
- **Per-field confidence and provenance.** A high-confidence company name and a
  low-confidence headcount guess don't get treated the same way.
- **Every field independently reversible** — accept, reject, one-step undo, unchanged
  from Smart Field.
- **Status only while working.** The surface is completely still whenever the agent
  isn't running and you're reviewing.

## Variants

### Ready

Notice the first field has an existing value — filling proposes *alongside* it rather
than overwriting, and nothing changes until accepted.

## Examples

Proposing for empty fields only, leaving anything the user already typed alone:

```tsx
const fields = ALL_FIELDS.filter((f) => !values[f.name]);
```

Gating the commit behind an approval when writing the form is consequential:

```tsx
<AIFormFill {...formProps} />
{dirty ? (
  <AIApprovalGate
    action={`Update the customer record with ${acceptedCount} AI-proposed values`}
    reversible
    impact={[{ label: "Fields changed", value: String(acceptedCount) }]}
    onApprove={save}
    onReject={revert}
  />
) : null}
```

## Props

| Prop | Type | Description |
| --- | --- | --- |
| `fields` | `FormFillField[]` | Required. `{ name, label, description?, placeholder?, fetchProposal }`. |
| `values` | `Record<string, string>` | Required. Controlled. |
| `onValueChange` | `(name, value) => void` | Required. |
| `onFill` | `() => void \| Promise<void>` | Runs once per request — fetch the batch here. |
| `triggerIcon` | `ReactNode` | Required. No icon set is bundled. |
| `fillLabel` | `string` | Defaults to `"Fill with AI"`. |
| `status` | `string` | Status text while filling. |

## Composes

`Smart Field` · `Field` · `AI Action Toolbar` · `Live Status Line` — and transitively
`Confidence Meter` and `Agent Presence`.

## When not to use

A single field is `Smart Field` used directly. Approving a consequential action is
`AI Approval Gate`. A full agent run with reasoning and interrupts is
`Thinking Experience`.

## Why it works this way

The load-bearing decision is what this block refuses to add. Bulk filling makes an 'Accept all' control feel obvious, and it is exactly wrong: Smart Field exists so that a proposed value is reviewed with its confidence and source before it becomes real data, and a single click that accepts twelve values with three different confidence tiers silently discards that. So the request is bulk and the review stays per-field — which is the honest reading of the system's 'nothing commits silently' rule rather than a convenience compromise. Making fields propose together required a small, consumer-driven addition to Smart Field rather than a workaround here: a `proposeToken` prop whose change requests a proposal. The alternatives were worse — remounting each field to re-fire `autoPropose` would have destroyed focus and in-flight requests, and hoisting proposal state into this block would have taken ownership of confidence, undo and abort away from the component that already does all of it correctly. The token deliberately ignores its first render, so mounting fields with a token present is not a request; that keeps unannounced fetching opt-in behind `autoPropose`, which is the posture the AI tier holds. `onFill` exists so the whole batch is one round trip: without it, a five-field form would make five separate model calls for a single user action, which is both slow and expensive in a way the user never asked for.

---

Follow the PixelDosa UI rules when building with this component: https://pixeldosa.akshayjayan.com/llms.txt

---

# Image Studio

> A whole workspace for making images — settings that survive the prompt, results as they land, and a history you can work from.

```bash
npx shadcn@latest add @pixeldosa/image-studio
```

Composes (installed automatically): `prompt-composer`, `parameter-panel`, `generation-job`, `variation-grid`, `credits-meter`.

**Before you use it:** Requires `cn` at `@/lib/utils`. Format every figure yourself — costs, times and totals are strings. `onRecall` should restore both the prompt and the settings, not just the prompt; restoring one without the other is the failure this history exists to fix.

## Usage

```tsx
"use client";

import { ImageStudio } from "@/components/blocks/image-studio";

<ImageStudio
  onGenerate={({ text }) => start(text)}
  groups={settingGroups}
  values={settings}
  onValueChange={(group, option) => setSettings({ ...settings, [group]: option })}
  credits={{ remaining: "1,250 credits", allowance: "2,000 this month", used: 0.38 }}
  run={run}
  history={history}
  onRecall={(id) => restore(id)}
/>
```

## Why it exists

Generation tools get described the same way: tossing prompts into a black hole. A feed
that scrolls instead of an overview, so finding the good result from last Tuesday means
scrolling past everything since. Settings that evaporate when you switch model, so you
restate the palette and the framing in every prompt. And no idea what a run will cost
until it's gone.

People work around all three with a spreadsheet of prompts kept beside the tool. This
block is the workspace that makes that spreadsheet unnecessary.

## Features

- **Settings sit beside the work and survive the prompt.** Picked from previews, not
  named from memory. Changing what you're asking for doesn't lose how you wanted it.
- **History is a grid you can recall from.** Each past run hands back its prompt *and*
  its settings — the thing a feed of images structurally cannot do.
- **Results appear as they land.** A finished image never waits for its siblings, and a
  failed one says so on its own tile.
- **The price is named before the click**, and the refund rule is stated before anything
  fails rather than after.
- **One place to stop.** Stop lives on the run; the composer just stops offering to start
  a second one on top of it.

## Props

| Prop | Type | Notes |
| --- | --- | --- |
| `onGenerate` | `(submission) => void` | Required. The composer's submission. |
| `groups` / `values` / `onValueChange` | `ParameterGroup[]` / `Record<string,string>` / `(groupId, optionId) => void` | Required. The settings rail. |
| `run` | `StudioRun \| null` | The run in progress or the one that just finished. |
| `credits` | `CreditsMeterProps` | Everything Credits Meter takes. |
| `history` | `StudioHistoryEntry[]` | Past runs, newest first. |
| `onRecall` | `(entryId: string) => void` | Restore a past run's prompt **and** settings. |
| `promptValue` / `onPromptValueChange` | `string` / `(value) => void` | Control the prompt, so Recall can fill it. |
| `onCancel` / `onRetry` | `() => void` | On the run. |
| `onKeptChange` / `onRegenerateRest` | `(ids: string[]) => void` | Keep the good ones, replace the rest. |
| `onUse` / `onMore` / `onRetryItem` | `(id: string) => void` | Per result. |
| `settingsSummary` | `string` | The current settings as a sentence. |
| `refundNote` / `regenerateCost` | `string` | Stated before the click. |
| `empty` | `{ title, description? }` | Before the first run. |
| `headingLevel` | `2 \| 3 \| 4 \| 5` | Defaults to `2`. |

`StudioRun` is `{ id, prompt, status, items, keptIds?, queue?, stage?, progress?, startedAt?, cost?, error? }`.
`StudioHistoryEntry` is `{ id, prompt, thumbnails, time?, settings?, total? }`.

## Accessibility

- One labelled section; the settings rail, the run and the history each carry their own
  heading at the level below it, so the page outline never skips.
- The settings are real radio groups in a `fieldset`, so arrow keys move between options.
- Results are a list of buttons, not a wall of images — keyboard users move through
  results rather than decorations.
- Only the running job animates; it stops under `prefers-reduced-motion`, and every state
  it carries is also in words.

## When not to use

- **One generation inside a chat thread:** use `Generation Job` on its own.
- **Choosing between two images:** that's `Compare View`.
- **A gallery of finished work:** this is a workspace for making things, not a portfolio.

## Notes

`onRecall` must restore both the prompt and the settings. Restoring only the prompt
recreates the exact problem the history exists to solve.

## Why it works this way

The layout encodes the three documented failures of generation workspaces. Settings live in a rail beside the work rather than inside the prompt, because the reviewed complaint about multi-model tools is that switching model reopens every consistency problem and leaves the user restating palette and framing by hand; a rail that survives the prompt is what stops that. History is a thumbnail grid with a recall control, not a feed: comparisons of the same review task put a grid at roughly five times the density of a scrolling list, and density is the whole job when you are looking for the good one from last Tuesday. Recall returns the settings as well as the prompt, which is the part a feed of images structurally cannot do. Partial results render inside the job rather than after it, so a finished image never waits for its siblings. The composer goes busy while a run is active instead of offering a second start on top of the first, and Stop stays on the job, where the run actually is, so there is exactly one place to end it.

---

Follow the PixelDosa UI rules when building with this component: https://pixeldosa.akshayjayan.com/llms.txt

---

# Thinking Experience

> A complete agent run, orchestrated — status, reasoning, questions, approvals and the result, with one state deciding what belongs on screen.

```bash
npx shadcn@latest add @pixeldosa/thinking-experience
```

Composes (installed automatically): `live-status-line`, `reasoning-stream`, `agent-ask`, `ai-approval-gate`, `ai-action-toolbar`, `agent-figure`.

**Before you use it:** Requires `cn` at `@/lib/utils`. Installing this pulls in the whole AI-tier stack it composes — Live Status Line, Reasoning Stream, Agent Ask, AI Approval Gate and AI Action Toolbar, plus Agent Presence, Confidence Meter and AI Context Surface transitively. Drive it from a single agent state; passing `ask` and `approval` alongside is harmless, since only the one matching the current state renders.

## Usage

```tsx
"use client";

import { ThinkingExperience } from "@/components/blocks/thinking-experience";

<ThinkingExperience
  state={run.state}
  status={run.status}
  detail={run.target}
  startedAt={run.startedAt}
  reasoning={run.reasoningSummaries}
  ask={pendingQuestion}
  approval={pendingApproval}
  result={<Summary data={run.result} />}
  resultActions={[{ id: "apply", label: "Apply", intent: "primary" }]}
  onCancel={run.abort}
/>
```

**This is a Block, not a component.** Every visible element comes from an
already-shipped component — what this adds is the orchestration.

## What it actually contributes

Wiring Live Status Line, Reasoning Stream, Agent Ask and AI Approval Gate together
yourself means re-deriving four decisions:

- **Which surface belongs on screen** at each state.
- **When reasoning stops streaming** — the moment control passes to a human, not
  whenever the text runs out.
- **When the elapsed counter freezes** — on terminal states, rather than counting
  forever.
- **What happens to the machine's surfaces while a person is being asked something.**

That last one is where most implementations go wrong, and it's the interesting part.

## The grammar, scaled up

At component level the turn-taking rule is one indicator moving or holding still. At
panel level it becomes **relative emphasis**: when control passes back, the agent's
status and reasoning step down (indicators fade, text drops to the muted colour but stays readable) and whatever needs an answer takes a ring.

Two deliberate choices there:

- **Dimmed, never disabled.** A run must stay stoppable even while it waits on you.
  `pointer-events-none` on that region would have silently removed the Stop control at
  exactly the moment someone might want it.
- **Emphasis by ring, not motion.** This is the user's turn, so stillness is the
  signal. Animating the thing that wants attention would contradict the rule the rest
  of the system holds.

## Variants

### Working

### Waiting for approval

Note the status and reasoning above the gate — still legible, still stoppable, visibly
no longer the point.

### Complete

<ThinkingExperience
    state="done"
    status="Reconciled 5 invoices"
    reasoning={["Three invoices share the same billing contact."]}
    reasoningMs={6400}
    result={<p className="text-sm text-foreground">The duplicate-payment warning had one root cause.</p>}
    resultActions={[{ id: "apply", label: "Apply", intent: "primary" }, { id: "explain", label: "Explain", intent: "quiet" }]}
  />

## Examples

Driving it from one state — passing `ask` and `approval` alongside is harmless, since
only the one matching the current state renders:

```tsx
<ThinkingExperience
  state={toAgentState(run)}
  status={run.status}
  ask={run.elicitation ? { ...toAsk(run.elicitation), onRespond: resume } : undefined}
  approval={run.interrupt ? { ...toApproval(run.interrupt), onApprove, onReject } : undefined}
/>
```

As a sidebar panel, where it's permanent chrome rather than a moment:

```tsx
<aside className="w-96 border-l p-3">
  <ThinkingExperience {...run} className="border-0 p-0" />
</aside>
```

## Props

| Prop | Type | Description |
| --- | --- | --- |
| `state` | `AgentState` | Required. Decides which surface renders. |
| `status` | `string` | Required. The current micro-action. |
| `detail` | `string` | What the action is acting on. |
| `startedAt` | `number \| Date` | Elapsed counter; freezes on terminal states. |
| `reasoning` | `string[]` | Reasoning summaries. |
| `reasoningMs` | `number` | Measured duration, shown once complete. |
| `ask` | `AskRequest` | Rendered when `state` is `asking`. |
| `approval` | `ApprovalRequest` | Rendered when `state` is `awaitingApproval`. |
| `result` | `ReactNode` | Rendered on terminal states. |
| `resultActions` | `AIAction[]` | Action strip beneath the result. |
| `onCancel` | `() => void` | Always available while active. |
| `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | Heading level, so the component fits your page's outline. Defaults to `3`. |
| `expression` | `"full" \| "subtle" \| "off"` | How much of the agent shows. `full` draws the whole figure beside the run, `subtle` keeps its head in the status line, `off` uses dots. Defaults to `"subtle"`. |

## Composes

`Live Status Line` · `Reasoning Stream` · `Agent Ask` · `AI Approval Gate` ·
`AI Action Toolbar` — and transitively `Agent Presence`, `Confidence Meter`,
`AI Context Surface`. Installing this pulls the whole stack.

## When not to use

This shows **one run in progress**, not a history of turns — it isn't a chat thread or
a transcript. For a single agent status in existing chrome without the surrounding
panel, use `Live Status Line` directly.

## Why it works this way

The first Block in this system, and it is deliberately an orchestration rather than new UI: every visible element comes from an already-shipped component. What it contributes is the set of decisions a consumer would otherwise have to re-derive — which surface belongs on screen at which state, that reasoning stops streaming the moment control passes to a human rather than continuing to tick behind a question, that the elapsed counter freezes on terminal states instead of counting forever, and that a pending question or approval is what the eye should land on. The interesting decision is how the turn-taking grammar scales: at component level it is one indicator moving or holding still, but at panel level it becomes relative emphasis, so the machine's status and reasoning step down (indicator graphics fade to 40% and primary text drops to the muted colour, keeping text above 4.5:1 contrast rather than dimming it with opacity) while an interrupt takes a ring. They are dimmed but deliberately never disabled — a run must remain stoppable even while it is waiting on the person, and `pointer-events-none` on that region would have silently removed the Stop control at exactly the moment someone might want it. Emphasis is carried by a ring rather than by animation because this is the user's turn and stillness is the signal; animating the thing that wants attention would contradict the grammar the rest of the system holds. Ask and approval are passed as plain data objects rather than as slots so the block owns the decision of when each appears — a slot-based API would hand the orchestration question straight back to the consumer, which is the one thing this component exists to answer.

---

Follow the PixelDosa UI rules when building with this component: https://pixeldosa.akshayjayan.com/llms.txt