# Trace

The building block for reasoning, tool calls, sources and more.

Source: https://webjs.dev/ui/docs/components/trace

```ts
import { html, nothing } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { bubbleClass, bubbleContentClass } from '#components/ui/bubble.ts';
import { buttonClass } from '#components/ui/button.ts';
import {
  codeBlockClass, codeBlockContentClass, codeBlockCodeClass,
} from '#components/ui/code-block.ts';
import { messageClass, messageContentClass } from '#components/ui/message.ts';
import {
  traceClass, traceLineClass, traceIconClass, traceTitleClass,
  traceCollapsibleClass, traceCollapsibleTriggerClass, traceCollapsibleContentClass,
} from '#components/ui/trace.ts';
import {
  ArrowUpRightIcon, ChevronRightIcon, CircleAlertIcon, CircleCheckIcon, GlobeIcon,
} from '#lib/ui/lucide.ts';

const question = 'Why does pnpm install fail in CI?';
const reasoning =
  'CI installs with a frozen lockfile, so the install stops when package.json and pnpm-lock.yaml disagree. I should check what the last commit changed, then reproduce the install.';
const answer =
  'The last commit bumped a version in package.json without updating pnpm-lock.yaml, so the frozen install fails. Run pnpm install locally and commit the lockfile.';
const sources = [
  { url: 'https://pnpm.io/cli/install#--frozen-lockfile', title: 'pnpm install | pnpm.io' },
  { url: 'https://pnpm.io/continuous-integration', title: 'Continuous Integration | pnpm.io' },
];

function TraceCollapsible(line: unknown, content: unknown, open = false) {
  return html`
    <details data-slot="trace-collapsible" ?open=${open} class=${cn(traceCollapsibleClass(), 'group/trace-collapsible')}>
      <summary data-slot="trace-collapsible-trigger" class=${traceCollapsibleTriggerClass()}>
        ${line}
        <span data-slot="trace-icon" aria-hidden="true" class=${cn(traceIconClass(), 'transition-transform group-open/trace-collapsible:rotate-90')}>${ChevronRightIcon()}</span>
      </summary>
      ${content}
    </details>
  `;
}

function ThinkingRow() {
  return TraceCollapsible(
    html`<span data-slot="trace-line" class=${traceLineClass()}>
      <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${CircleCheckIcon()}</span>
      <span data-slot="trace-title" class=${traceTitleClass()}>Thought for 5s</span>
    </span>`,
    html`<div data-slot="trace-collapsible-content" class=${cn(traceCollapsibleContentClass(), 'whitespace-pre-wrap')}>${reasoning}</div>`,
  );
}

function ToolRow(command: string, result: { stdout?: string; errorText?: string }, defaultOpen = false) {
  const failed = result.errorText !== undefined;
  return TraceCollapsible(
    html`<span data-slot="trace-line" data-status=${failed ? 'error' : nothing} class=${traceLineClass()}>
      <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${failed ? CircleAlertIcon() : CircleCheckIcon()}</span>
      <span data-slot="trace-title" class=${traceTitleClass()}>${failed ? 'Failed to run' : 'Ran'} ${command}</span>
    </span>`,
    html`<div data-slot="trace-collapsible-content" class=${traceCollapsibleContentClass()}>
      <div data-slot="code-block" data-variant=${failed ? 'destructive' : 'default'} data-size="sm" class=${codeBlockClass({ variant: failed ? 'destructive' : 'default' })}>
        <pre data-slot="code-block-content" data-wrap tabindex="0" dir="ltr" style="counter-reset: line 0" class=${cn(codeBlockContentClass(), 'max-h-64')}><code data-slot="code-block-code" class=${codeBlockCodeClass()}>${failed ? result.errorText : result.stdout}</code></pre>
      </div>
    </div>`,
    defaultOpen,
  );
}

function SourcesRow() {
  return TraceCollapsible(
    html`<span data-slot="trace-line" class=${traceLineClass()}>
      <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${GlobeIcon()}</span>
      <span data-slot="trace-title" class=${traceTitleClass()}>Used ${sources.length} sources</span>
    </span>`,
    html`<div data-slot="trace-collapsible-content" class=${traceCollapsibleContentClass()}>
      <div data-slot="trace" class=${traceClass()}>
        ${sources.map((source) => html`
          <a href=${source.url} target="_blank" rel="noreferrer">
            <span data-slot="trace-line" class=${traceLineClass()}>
              <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${GlobeIcon()}</span>
              <span data-slot="trace-title" class=${traceTitleClass()}>
                ${source.title}
                <span class="sr-only"> (opens in a new tab)</span>
              </span>
              <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${ArrowUpRightIcon()}</span>
            </span>
          </a>
        `)}
      </div>
    </div>`,
  );
}

export default function TraceDemo() {
  return html`
    <div class="flex min-h-72 w-full max-w-sm flex-col gap-4 py-6 text-sm">
      <div data-slot="message" data-align="end" class=${messageClass()}>
        <div data-slot="message-content" class=${messageContentClass()}>
          <div data-slot="bubble" data-variant="muted" data-align="end" class=${bubbleClass({ variant: 'muted' })}>
            <div data-slot="bubble-content" class=${bubbleContentClass()}>${question}</div>
          </div>
        </div>
      </div>
      <div data-slot="message" data-align="start" class=${messageClass()}>
        <div data-slot="message-content" class=${cn(messageContentClass(), 'gap-4')}>
          <div data-slot="trace" class=${traceClass()}>
            ${ThinkingRow()}
            ${ToolRow('pnpm --version', { stdout: '10.18.0' })}
            ${ToolRow(
              'git diff --stat HEAD~1 -- package.json pnpm-lock.yaml',
              { stdout: ' package.json | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)' },
              true,
            )}
            ${ToolRow('pnpm install --frozen-lockfile', {
              errorText: 'ERR_PNPM_OUTDATED_LOCKFILE  Cannot install with "frozen-lockfile" because pnpm-lock.yaml is not up to date with package.json',
            })}
            ${SourcesRow()}
          </div>
          <p>${answer}</p>
        </div>
      </div>
      <button type="button" data-slot="button" data-variant="outline" data-size="sm" class=${cn(buttonClass({ variant: 'outline', size: 'sm' }), 'mt-auto self-start')}>
        Replay
      </button>
    </div>
  `;
}
```

A trace is a list of lines. Each line has an icon, a title, and an optional description and status. A line can expand to show more detail, link to a page, or open a dialog or sheet.

Every line has the same shape, so reasoning, tool calls, sources and plans built from a trace look and behave the same.

Use a trace for the steps an agent takes, like calling a tool, running a subagent or editing a file. Use [Message](https://webjs.dev/ui/docs/components/message) for its reply, and [Marker](https://webjs.dev/ui/docs/components/marker) for notes and dividers between turns.

## Built with Trace

Every pattern below is a composition of trace parts. See [AI Elements](https://webjs.dev/ui/docs/ai-elements) for examples and code.

| Pattern | Shows |
| --- | --- |
| [Chain of Thought](https://webjs.dev/ui/docs/ai-elements/chain-of-thought) | A summary that expands into the steps behind it. |
| [Plan](https://webjs.dev/ui/docs/ai-elements/plan) | The steps the agent plans to take, and how far it has got. |
| [Queue](https://webjs.dev/ui/docs/ai-elements/queue) | The agent's todo list, split into what is left and what is done. |
| [Reasoning](https://webjs.dev/ui/docs/ai-elements/reasoning) | The agent's thinking as it streams. |
| [Sources](https://webjs.dev/ui/docs/ai-elements/sources) | The links the agent used for a reply. |
| [Stack Trace](https://webjs.dev/ui/docs/ai-elements/stack-trace) | A failed tool call and its stack frames. |
| [Subagent](https://webjs.dev/ui/docs/ai-elements/subagent) | A subagent run, with its tool calls and result. |
| [Task](https://webjs.dev/ui/docs/ai-elements/task) | The steps the agent takes, as it takes them. |
| [Terminal](https://webjs.dev/ui/docs/ai-elements/terminal) | A command the agent runs, with its output as it streams. |
| [Test Results](https://webjs.dev/ui/docs/ai-elements/test-results) | A test run by the agent, with its suites and failures. |
| [Tool](https://webjs.dev/ui/docs/ai-elements/tool) | A tool call the agent makes, from input to output. |

## Installation

```bash
npx @webjsdev/ui add trace
```

### Copy and paste the following code into your project.

````ts title="components/ui/trace.ts"
/**
 * Trace: a vertical timeline of steps (a tool call, a reasoning step, a
 * deploy stage), each with an icon on a connecting line, a title and an
 * optional collapsible detail. Tier-1 class helper; compose with plain
 * elements and `<details>` for the collapsible part.
 *
 * shadcn parity:
 *   Trace                       → traceClass()
 *   TraceLine / TraceIcon       → traceLineClass() / traceIconClass()
 *   TraceTitle / TraceDescription
 *                               → traceTitleClass() / traceDescriptionClass()
 *   TraceCollapsible / TraceCollapsibleTrigger / TraceCollapsibleContent
 *                               → <details> / <summary> / a div, with the
 *                                 trace collapsible helpers
 *
 * shadcn has no new-york version of this component, so its look in the
 * default style is shadcn's vega style, the classic shadcn look.
 *
 * A11y (required for accessible output): a trace is an ordered list of steps,
 * so render it as `<ol>` with each step an `<li>`. A step's status must be in
 * text, not only in the icon colour ("Failed", "Done"), and a decorative icon
 * takes `aria-hidden="true"`. A collapsible step is a native `<details>` with a
 * `<summary>`, which carries the expanded state by itself.
 *
 * Design tokens used: --border, --muted-foreground, --foreground.
 *
 * @example
 * ```html
 * <ol class=${traceClass()} data-slot="trace">
 *   <li class=${traceLineClass()} data-slot="trace-line">
 *     <span class=${traceTitleClass()} data-slot="trace-title">Fetched the issue</span>
 *   </li>
 * </ol>
 * ```
 */

/** Set `data-slot="trace"` on the element. */
export function traceClass(): string {
  return 'gap-2 *:has-[>[data-slot=trace-line]]:rounded-md *:has-[>[data-slot=trace-line]]:focus-visible:ring-3 *:has-[>[data-slot=trace-line]]:focus-visible:ring-ring/50 flex w-full min-w-0 flex-col *:has-[>[data-slot=trace-line]]:flex *:has-[>[data-slot=trace-line]]:w-fit *:has-[>[data-slot=trace-line]]:max-w-full *:has-[>[data-slot=trace-line]]:min-w-0 *:has-[>[data-slot=trace-line]]:text-start *:has-[>[data-slot=trace-line]]:outline-none';
}

/** Set `data-slot="trace-line"` on the element. */
export function traceLineClass(): string {
  return 'gap-2 text-sm flex w-fit max-w-full min-w-0 items-center text-muted-foreground transition-colors in-[a,button]:cursor-pointer in-[a:hover,button:hover]:text-foreground data-[status=error]:text-destructive data-[status=error]:in-[a:hover,button:hover]:text-destructive data-[status=pending]:opacity-60 data-[status=running]:*:data-[slot=trace-title]:shimmer';
}

/** Set `data-slot="trace-icon"` on the element. */
export function traceIconClass(): string {
  return "size-4 [&_svg:not([class*='size-'])]:size-4 [[data-slot=trace-title]~&]:-ms-1 flex shrink-0 items-center justify-center [&_svg]:pointer-events-none";
}

/** Set `data-slot="trace-title"` on the element. */
export function traceTitleClass(): string {
  return 'min-w-0 truncate motion-reduce:shimmer-none';
}

/** Set `data-slot="trace-description"` on the element. */
export function traceDescriptionClass(): string {
  return 'shrink-0 text-muted-foreground/70 tabular-nums';
}

/** Set `data-slot="trace-collapsible"` on the element. */
export function traceCollapsibleClass(): string {
  return 'flex w-full min-w-0 flex-col';
}

/** Set `data-slot="trace-collapsible-trigger"` on the element. */
export function traceCollapsibleTriggerClass(): string {
  return 'gap-1 rounded-md focus-visible:ring-3 focus-visible:ring-ring/50 group/trace-collapsible-trigger flex w-fit max-w-full min-w-0 cursor-pointer items-center text-start text-muted-foreground transition-colors outline-none hover:text-foreground has-[[data-status=error]]:text-destructive';
}

/** Set `data-slot="trace-collapsible-content"` on the element. */
export function traceCollapsibleContentClass(): string {
  return 'mt-2 mb-1 ms-[calc(--spacing(2)-1px)] border-s pe-1 ps-4 leading-relaxed min-w-0 wrap-break-word text-muted-foreground';
}
````

### Update the import paths to match your project setup.

## Usage

Use a trace line for a single step:

```ts
import {
  traceClass, traceLineClass, traceIconClass, traceTitleClass,
} from '#components/ui/trace.ts';
```

```ts
<div data-slot="trace" class=${traceClass()}>
  <span data-slot="trace-line" class=${traceLineClass()}>
    <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>
      ${SearchIcon()}
    </span>
    <span data-slot="trace-title" class=${traceTitleClass()}>Searched for minimumReleaseAge</span>
  </span>
</div>
```

Wrap the line in a collapsible row to show more detail when it expands. The row is a native `<details>`, its trigger the `<summary>`:

```ts
import {
  traceClass,
  traceCollapsibleClass,
  traceCollapsibleContentClass,
  traceCollapsibleTriggerClass,
  traceIconClass,
  traceLineClass,
  traceTitleClass,
} from '#components/ui/trace.ts';
```

```ts
<div data-slot="trace" class=${traceClass()}>
  <details data-slot="trace-collapsible" class=${cn(traceCollapsibleClass(), 'group/trace-collapsible')}>
    <summary data-slot="trace-collapsible-trigger" class=${traceCollapsibleTriggerClass()}>
      <span data-slot="trace-line" class=${traceLineClass()}>
        <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>
          ${TerminalIcon()}
        </span>
        <span data-slot="trace-title" class=${traceTitleClass()}>Ran node --version</span>
      </span>
      <span data-slot="trace-icon" aria-hidden="true" class=${cn(traceIconClass(), 'transition-transform group-open/trace-collapsible:rotate-90')}>
        ${ChevronRightIcon()}
      </span>
    </summary>
    <div data-slot="trace-collapsible-content" class=${traceCollapsibleContentClass()}>v24.18.0</div>
  </details>
</div>
```

## Composition

Use the following composition to build a trace line:

```text
trace
└── trace-line
    ├── trace-icon
    ├── trace-title
    ├── trace-description
    └── trace-icon
```

Wrap the line in a collapsible row to show more detail when it expands:

```text
trace
└── trace-collapsible            <details>
    ├── trace-collapsible-trigger <summary>
    │   └── trace-line
    └── trace-collapsible-content
```

The trace line is always the line. To make a line do something, wrap it in that thing's trigger.

## Features

- One row for reasoning, tool calls, sources, plans and tasks
- Rows that expand, link out, or open a dialog, sheet, drawer or popover
- `running`, `error` and `pending` states on `data-status`, with a shimmer while running
- Nested rows, so a summary expands into steps and a step into its output
- Maps one to one onto the reasoning, tool and source parts of the AI SDK
- Keyboard and screen reader support from the native element that wraps each row
- Customizable styling by merging your classes with each helper through `cn()`

## Trace Line

Use a trace line on its own for a step with no detail to show. It reads as plain text.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import {
  traceClass, traceLineClass, traceIconClass, traceTitleClass,
} from '#components/ui/trace.ts';
import { GitBranchIcon } from '#lib/ui/lucide.ts';

export default function TraceStatic() {
  return html`
    <div data-slot="trace" class=${cn(traceClass(), 'max-w-sm')}>
      <span data-slot="trace-line" class=${traceLineClass()}>
        <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${GitBranchIcon()}</span>
        <span data-slot="trace-title" class=${traceTitleClass()}>Created branch fix/frozen-lockfile</span>
      </span>
    </div>
  `;
}
```

## Status

Set `data-status` on the trace line when a step is running, has failed or hasn't started yet.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import {
  traceClass, traceLineClass, traceIconClass, traceTitleClass,
} from '#components/ui/trace.ts';
import {
  CircleAlertIcon, CircleCheckIcon, CircleIcon, LoaderCircleIcon,
} from '#lib/ui/lucide.ts';

export default function TraceStatus() {
  return html`
    <div data-slot="trace" class=${cn(traceClass(), 'max-w-sm')}>
      <span data-slot="trace-line" class=${traceLineClass()}>
        <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${CircleCheckIcon()}</span>
        <span data-slot="trace-title" class=${traceTitleClass()}>Ran pnpm install</span>
      </span>
      <span data-slot="trace-line" data-status="error" class=${traceLineClass()}>
        <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${CircleAlertIcon()}</span>
        <span data-slot="trace-title" class=${traceTitleClass()}>Failed to run pnpm lint</span>
      </span>
      <span data-slot="trace-line" data-status="running" class=${traceLineClass()}>
        <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${LoaderCircleIcon('animate-spin')}</span>
        <span data-slot="trace-title" class=${traceTitleClass()}>Running pnpm build</span>
      </span>
      <span data-slot="trace-line" data-status="pending" class=${traceLineClass()}>
        <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${CircleIcon()}</span>
        <span data-slot="trace-title" class=${traceTitleClass()}>Run pnpm test</span>
      </span>
    </div>
  `;
}
```

| Status | Use for |
| --- | --- |
| none | Work that is done: "Ran pnpm install". |
| `"error"` | Work that failed. Say so in the title: "Failed to run pnpm lint". |
| `"running"` | Work in progress. Write the title in the present tense: "Running pnpm build". |
| `"pending"` | Work that has not started, such as a plan step: "Run pnpm test". |

## Description

Put secondary text such as a diff stat, a duration or a count in a trace description after the title. It does not truncate.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import {
  traceClass, traceLineClass, traceIconClass, traceTitleClass, traceDescriptionClass,
} from '#components/ui/trace.ts';
import { FilePenIcon, SearchIcon, TerminalIcon } from '#lib/ui/lucide.ts';

export default function TraceDescriptionDemo() {
  return html`
    <div data-slot="trace" class=${cn(traceClass(), 'max-w-sm')}>
      <span data-slot="trace-line" class=${traceLineClass()}>
        <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${FilePenIcon()}</span>
        <span data-slot="trace-title" class=${traceTitleClass()}>
          Edited components/settings/notification-preferences-form.tsx
        </span>
        <span data-slot="trace-description" class=${cn(traceDescriptionClass(), 'font-mono')}>+48 −12</span>
      </span>
      <span data-slot="trace-line" class=${traceLineClass()}>
        <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${TerminalIcon()}</span>
        <span data-slot="trace-title" class=${traceTitleClass()}>Ran pnpm test</span>
        <span data-slot="trace-description" class=${traceDescriptionClass()}>14s</span>
      </span>
      <span data-slot="trace-line" class=${traceLineClass()}>
        <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${SearchIcon()}</span>
        <span data-slot="trace-title" class=${traceTitleClass()}>Searched for useChat</span>
        <span data-slot="trace-description" class=${traceDescriptionClass()}>8 results</span>
      </span>
    </div>
  `;
}
```

## Collapsible

Wrap the line in a collapsible row to show more detail when it expands. Put the trace line inside the `<summary>` and the detail in the content after it.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import {
  codeBlockClass, codeBlockContentClass, codeBlockCodeClass,
} from '#components/ui/code-block.ts';
import {
  traceLineClass, traceIconClass, traceTitleClass,
  traceCollapsibleClass, traceCollapsibleTriggerClass, traceCollapsibleContentClass,
} from '#components/ui/trace.ts';
import { ChevronRightIcon, TerminalIcon } from '#lib/ui/lucide.ts';

// A collapsible row is a native details element: the summary is the trigger,
// and it carries the expanded state with no script.
export default function TraceCollapsibleDemo() {
  return html`
    <div class="w-full max-w-sm">
      <details data-slot="trace-collapsible" class=${cn(traceCollapsibleClass(), 'group/trace-collapsible')}>
        <summary data-slot="trace-collapsible-trigger" class=${traceCollapsibleTriggerClass()}>
          <span data-slot="trace-line" class=${traceLineClass()}>
            <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${TerminalIcon()}</span>
            <span data-slot="trace-title" class=${traceTitleClass()}>Ran node --version</span>
          </span>
          <span data-slot="trace-icon" aria-hidden="true" class=${cn(traceIconClass(), 'transition-transform group-open/trace-collapsible:rotate-90')}>${ChevronRightIcon()}</span>
        </summary>
        <div data-slot="trace-collapsible-content" class=${traceCollapsibleContentClass()}>
          <div data-slot="code-block" data-variant="default" data-size="sm" class=${codeBlockClass()}>
            <pre data-slot="code-block-content" data-wrap tabindex="0" dir="ltr" style="counter-reset: line 0" class=${cn(codeBlockContentClass(), 'max-h-64')}><code data-slot="code-block-code" class=${codeBlockCodeClass()}>${'$ node --version\nv24.18.0'}</code></pre>
          </div>
        </div>
      </details>
    </div>
  `;
}
```

## Open State

Rows start closed. Add the `open` attribute to the `<details>` to start open, or set its `open` property from script to control a row. The element fires `toggle` whenever it opens or closes.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { buttonClass } from '#components/ui/button.ts';
import {
  codeBlockClass, codeBlockContentClass, codeBlockCodeClass,
} from '#components/ui/code-block.ts';
import {
  traceLineClass, traceIconClass, traceTitleClass,
  traceCollapsibleClass, traceCollapsibleTriggerClass, traceCollapsibleContentClass,
} from '#components/ui/trace.ts';
import { ChevronRightIcon, TerminalIcon } from '#lib/ui/lucide.ts';

function Row(command: string, output: string, open: boolean) {
  return html`
    <details data-slot="trace-collapsible" ?open=${open} class=${cn(traceCollapsibleClass(), 'group/trace-collapsible')}>
      <summary data-slot="trace-collapsible-trigger" class=${traceCollapsibleTriggerClass()}>
        <span data-slot="trace-line" class=${traceLineClass()}>
          <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${TerminalIcon()}</span>
          <span data-slot="trace-title" class=${traceTitleClass()}>Ran ${command}</span>
        </span>
        <span data-slot="trace-icon" aria-hidden="true" class=${cn(traceIconClass(), 'transition-transform group-open/trace-collapsible:rotate-90')}>${ChevronRightIcon()}</span>
      </summary>
      <div data-slot="trace-collapsible-content" class=${traceCollapsibleContentClass()}>
        <div data-slot="code-block" data-variant="default" data-size="sm" class=${codeBlockClass()}>
          <pre data-slot="code-block-content" data-wrap tabindex="0" dir="ltr" style="counter-reset: line 0" class=${cn(codeBlockContentClass(), 'max-h-64')}><code data-slot="code-block-code" class=${codeBlockCodeClass()}>${output}</code></pre>
        </div>
      </div>
    </details>
  `;
}

// The first row starts open through the details element's open attribute.
// The second starts closed; script opens it by setting the element's open
// property, which is what the button below would do.
export default function TraceOpen() {
  return html`
    <div class="flex w-full max-w-sm flex-col items-start gap-4">
      ${Row('node --version', '$ node --version\nv24.18.0', true)}
      ${Row('pnpm --version', '$ pnpm --version\n10.33.4', false)}
      <button type="button" data-slot="button" data-variant="outline" data-size="sm" class=${buttonClass({ variant: 'outline', size: 'sm' })}>
        Show the pnpm output
      </button>
    </div>
  `;
}
```

To open a row while it streams and let the reader's click win, keep the reader's choice apart from the streaming state, and take over the summary's click so the row shows exactly what the component renders:

```ts
class ThinkingRow extends WebComponent({ running: Boolean, text: String }) {
  // undefined until the reader clicks the row.
  chosen = signal<boolean | undefined>(undefined);

  render() {
    const open = this.chosen.get() ?? this.running;
    return html`<details data-slot="trace-collapsible" ?open=${open} class=${traceCollapsibleClass()}>
      <summary
        data-slot="trace-collapsible-trigger"
        class=${traceCollapsibleTriggerClass()}
        @click=${(e: Event) => { e.preventDefault(); this.chosen.set(!open); }}
      >
        <span data-slot="trace-line" data-status=${this.running ? 'running' : nothing} class=${traceLineClass()}>…</span>
      </summary>
      <div data-slot="trace-collapsible-content" class=${traceCollapsibleContentClass()}>${this.text}</div>
    </details>`;
  }
}
```

## Link

Wrap the trace line in an anchor. For a new tab, use an arrow-up-right icon and sr-only "(opens in a new tab)".

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import {
  traceClass, traceLineClass, traceIconClass, traceTitleClass,
} from '#components/ui/trace.ts';
import {
  ArrowUpRightIcon, ChevronRightIcon, FileTextIcon, GlobeIcon,
} from '#lib/ui/lucide.ts';

export default function TraceLink() {
  return html`
    <div data-slot="trace" class=${cn(traceClass(), 'max-w-sm')}>
      <a href="#link">
        <span data-slot="trace-line" class=${traceLineClass()}>
          <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${FileTextIcon()}</span>
          <span data-slot="trace-title" class=${traceTitleClass()}>Read apps/v4/lib/docs.ts</span>
          <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${ChevronRightIcon()}</span>
        </span>
      </a>
      <a href="https://docs.astro.build/en/install-and-setup/" target="_blank" rel="noreferrer">
        <span data-slot="trace-line" class=${traceLineClass()}>
          <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${GlobeIcon()}</span>
          <span data-slot="trace-title" class=${traceTitleClass()}>
            Install Astro | docs.astro.build
            <span class="sr-only"> (opens in a new tab)</span>
          </span>
          <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${ArrowUpRightIcon()}</span>
        </span>
      </a>
    </div>
  `;
}
```

```ts
<a href="https://docs.astro.build" target="_blank" rel="noreferrer">
  <span data-slot="trace-line" class=${traceLineClass()}>
    <span data-slot="trace-title" class=${traceTitleClass()}>
      Install Astro
      <span class="sr-only"> (opens in a new tab)</span>
    </span>
    <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>
      ${ArrowUpRightIcon()}
    </span>
  </span>
</a>
```

## Dialog

Wrap the trace line in a button inside `<ui-dialog-trigger>`. The dialog owns its open state, Escape and focus return.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import {
  dialogHeaderClass, dialogTitleClass, dialogDescriptionClass,
} from '#components/ui/dialog.ts';
import {
  traceClass, traceLineClass, traceIconClass, traceTitleClass,
} from '#components/ui/trace.ts';
import { ArrowUpRightIcon, ChevronRightIcon, GlobeIcon } from '#lib/ui/lucide.ts';

const results = [
  {
    title: 'Caching build outputs',
    url: 'https://nextjs.org/docs/app/guides/caching',
  },
  {
    title: 'Image optimization reference',
    url: 'https://nextjs.org/docs/app/api-reference/components/image',
  },
  {
    title: 'Deploy hooks and cache keys',
    url: 'https://vercel.com/docs/deploy-hooks',
  },
];

// The dialog's trigger wraps the line in a button, and the dialog owns the
// open state, Escape and the focus return.
export default function TraceDialog() {
  return html`
    <div data-slot="trace" class=${cn(traceClass(), 'max-w-sm')}>
      <ui-dialog>
        <ui-dialog-trigger>
          <button type="button" class="flex w-fit max-w-full min-w-0 text-start outline-none">
            <span data-slot="trace-line" class=${traceLineClass()}>
              <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${GlobeIcon()}</span>
              <span data-slot="trace-title" class=${traceTitleClass()}>Searched the web for cache keys</span>
              <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${ChevronRightIcon()}</span>
            </span>
          </button>
        </ui-dialog-trigger>
        <ui-dialog-content>
          <div data-slot="dialog-header" class=${dialogHeaderClass()}>
            <h2 data-slot="dialog-title" class=${dialogTitleClass()}>Searched the web for cache keys</h2>
            <p data-slot="dialog-description" class=${dialogDescriptionClass()}>
              Three results were used in the response.
            </p>
          </div>
          <div data-slot="trace" class=${traceClass()}>
            ${results.map((result) => html`
              <a href=${result.url} target="_blank" rel="noreferrer">
                <span data-slot="trace-line" class=${traceLineClass()}>
                  <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${GlobeIcon()}</span>
                  <span data-slot="trace-title" class=${traceTitleClass()}>
                    ${result.title}
                    <span class="sr-only"> (opens in a new tab)</span>
                  </span>
                  <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${ArrowUpRightIcon()}</span>
                </span>
              </a>
            `)}
          </div>
        </ui-dialog-content>
      </ui-dialog>
    </div>
  `;
}
```

```ts
<ui-dialog>
  <ui-dialog-trigger>
    <button type="button">
      <span data-slot="trace-line" class=${traceLineClass()}>
        <span data-slot="trace-title" class=${traceTitleClass()}>Searched the web for cache keys</span>
        <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>
          ${ChevronRightIcon()}
        </span>
      </span>
    </button>
  </ui-dialog-trigger>
  <ui-dialog-content>…</ui-dialog-content>
</ui-dialog>
```

## Sheet

The same shape as the dialog, with `<ui-sheet>`. Drawer and Popover work the same way.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import {
  sheetHeaderClass, sheetTitleClass, sheetDescriptionClass,
} from '#components/ui/sheet.ts';
import {
  traceClass, traceLineClass, traceIconClass, traceTitleClass,
} from '#components/ui/trace.ts';
import { ChevronRightIcon, FolderSearchIcon } from '#lib/ui/lucide.ts';

export default function TraceSheet() {
  return html`
    <div data-slot="trace" class=${cn(traceClass(), 'max-w-sm')}>
      <ui-sheet>
        <ui-sheet-trigger>
          <button type="button" class="flex w-fit max-w-full min-w-0 text-start outline-none">
            <span data-slot="trace-line" class=${traceLineClass()}>
              <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${FolderSearchIcon()}</span>
              <span data-slot="trace-title" class=${traceTitleClass()}>Explored 4 files</span>
              <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${ChevronRightIcon()}</span>
            </span>
          </button>
        </ui-sheet-trigger>
        <ui-sheet-content side="right">
          <div data-slot="sheet-header" class=${sheetHeaderClass()}>
            <h2 data-slot="sheet-title" class=${sheetTitleClass()}>Explored 4 files</h2>
            <p data-slot="sheet-description" class=${sheetDescriptionClass()}>
              Files read while preparing the response.
            </p>
          </div>
          <ul class="flex flex-col gap-2 px-6 font-mono text-xs">
            <li>apps/v4/lib/docs.ts</li>
            <li>apps/v4/lib/components.ts</li>
            <li>apps/v4/next.config.mjs</li>
            <li>apps/v4/package.json</li>
          </ul>
        </ui-sheet-content>
      </ui-sheet>
    </div>
  `;
}
```

## Group

Put rows that sit next to each other in a trace. It also styles any trigger or link that wraps a trace line.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import {
  traceClass, traceLineClass, traceIconClass, traceTitleClass,
} from '#components/ui/trace.ts';
import { FileTextIcon, SearchIcon, TerminalIcon } from '#lib/ui/lucide.ts';

export default function TraceGroupDemo() {
  return html`
    <div data-slot="trace" class=${cn(traceClass(), 'max-w-sm')}>
      <span data-slot="trace-line" class=${traceLineClass()}>
        <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${SearchIcon()}</span>
        <span data-slot="trace-title" class=${traceTitleClass()}>Searched for minimumReleaseAge</span>
      </span>
      <span data-slot="trace-line" class=${traceLineClass()}>
        <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${FileTextIcon()}</span>
        <span data-slot="trace-title" class=${traceTitleClass()}>Read pnpm-workspace.yaml</span>
      </span>
      <span data-slot="trace-line" class=${traceLineClass()}>
        <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${TerminalIcon()}</span>
        <span data-slot="trace-title" class=${traceTitleClass()}>Ran pnpm install</span>
      </span>
    </div>
  `;
}
```

## Sources

A collapsible row whose detail is a trace of link rows.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import {
  traceClass, traceLineClass, traceIconClass, traceTitleClass,
  traceCollapsibleClass, traceCollapsibleTriggerClass, traceCollapsibleContentClass,
} from '#components/ui/trace.ts';
import { ArrowUpRightIcon, ChevronRightIcon, GlobeIcon } from '#lib/ui/lucide.ts';

const sources = [
  {
    title: 'Install Astro | docs.astro.build',
    href: 'https://docs.astro.build/en/install-and-setup/',
  },
  {
    title: 'create-astro | npmjs.com',
    href: 'https://www.npmjs.com/package/create-astro',
  },
  {
    title: 'Settings: minimumReleaseAge | pnpm.io',
    href: 'https://pnpm.io/settings#minimumreleaseage',
  },
];

export default function TraceSources() {
  return html`
    <div class="w-full max-w-sm">
      <details data-slot="trace-collapsible" open class=${cn(traceCollapsibleClass(), 'group/trace-collapsible')}>
        <summary data-slot="trace-collapsible-trigger" class=${traceCollapsibleTriggerClass()}>
          <span data-slot="trace-line" class=${traceLineClass()}>
            <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${GlobeIcon()}</span>
            <span data-slot="trace-title" class=${traceTitleClass()}>Used ${sources.length} sources</span>
          </span>
          <span data-slot="trace-icon" aria-hidden="true" class=${cn(traceIconClass(), 'transition-transform group-open/trace-collapsible:rotate-90')}>${ChevronRightIcon()}</span>
        </summary>
        <div data-slot="trace-collapsible-content" class=${traceCollapsibleContentClass()}>
          <div data-slot="trace" class=${traceClass()}>
            ${sources.map((source) => html`
              <a href=${source.href} target="_blank" rel="noreferrer">
                <span data-slot="trace-line" class=${traceLineClass()}>
                  <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${GlobeIcon()}</span>
                  <span data-slot="trace-title" class=${traceTitleClass()}>
                    ${source.title}
                    <span class="sr-only"> (opens in a new tab)</span>
                  </span>
                  <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${ArrowUpRightIcon()}</span>
                </span>
              </a>
            `)}
          </div>
        </div>
      </details>
    </div>
  `;
}
```

See [Sources](https://webjs.dev/ui/docs/ai-elements/sources) for more examples.

## Chain of Thought

A chain of thought is a collapsible row with step rows inside. Set the parent's status and title from its children.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { badgeClass } from '#components/ui/badge.ts';
import {
  codeBlockClass, codeBlockContentClass, codeBlockCodeClass,
} from '#components/ui/code-block.ts';
import {
  traceClass, traceLineClass, traceIconClass, traceTitleClass,
  traceCollapsibleClass, traceCollapsibleTriggerClass, traceCollapsibleContentClass,
} from '#components/ui/trace.ts';
import { ChevronRightIcon, FileTextIcon, SearchIcon } from '#lib/ui/lucide.ts';

// A collapsible row: a details element whose summary holds the line, and a
// chevron that turns while it is open.
function TraceCollapsible(line: unknown, content: unknown, open = false) {
  return html`
    <details data-slot="trace-collapsible" ?open=${open} class=${cn(traceCollapsibleClass(), 'group/trace-collapsible')}>
      <summary data-slot="trace-collapsible-trigger" class=${traceCollapsibleTriggerClass()}>
        ${line}
        <span data-slot="trace-icon" aria-hidden="true" class=${cn(traceIconClass(), 'transition-transform group-open/trace-collapsible:rotate-90')}>${ChevronRightIcon()}</span>
      </summary>
      ${content}
    </details>
  `;
}

export default function TraceSteps() {
  return html`
    <div class="w-full max-w-sm">
      ${TraceCollapsible(
        html`<span data-slot="trace-line" data-status="running" class=${traceLineClass()}>
          <span data-slot="trace-title" class=${traceTitleClass()}>Looking into the slow deploy</span>
        </span>`,
        html`<div data-slot="trace-collapsible-content" class=${traceCollapsibleContentClass()}>
          <div data-slot="trace" class=${traceClass()}>
            ${TraceCollapsible(
              html`<span data-slot="trace-line" class=${traceLineClass()}>
                <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${SearchIcon()}</span>
                <span data-slot="trace-title" class=${traceTitleClass()}>Searched for the checkout build log</span>
              </span>`,
              html`<div data-slot="trace-collapsible-content" class=${cn(traceCollapsibleContentClass(), 'flex flex-wrap gap-1.5')}>
                <span data-slot="badge" data-variant="secondary" class=${badgeClass({ variant: 'secondary' })}>vercel.com</span>
                <span data-slot="badge" data-variant="secondary" class=${badgeClass({ variant: 'secondary' })}>github.com</span>
              </div>`,
            )}
            <a href="#steps">
              <span data-slot="trace-line" class=${traceLineClass()}>
                <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${FileTextIcon()}</span>
                <span data-slot="trace-title" class=${traceTitleClass()}>Read the last twelve deploys</span>
                <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${ChevronRightIcon()}</span>
              </span>
            </a>
            ${TraceCollapsible(
              html`<span data-slot="trace-line" data-status="running" class=${traceLineClass()}>
                <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${SearchIcon()}</span>
                <span data-slot="trace-title" class=${traceTitleClass()}>Searching for the cache key</span>
              </span>`,
              html`<div data-slot="trace-collapsible-content" class=${traceCollapsibleContentClass()}>
                <div data-slot="code-block" data-variant="default" data-size="sm" class=${codeBlockClass()}>
                  <pre data-slot="code-block-content" data-wrap tabindex="0" dir="ltr" style="counter-reset: line 0" class=${cn(codeBlockContentClass(), 'max-h-64')}><code data-slot="code-block-code" class=${codeBlockCodeClass()}>cache key image optimization</code></pre>
                </div>
              </div>`,
            )}
          </div>
        </div>`,
        true,
      )}
    </div>
  `;
}
```

See [Chain of Thought](https://webjs.dev/ui/docs/ai-elements/chain-of-thought) and [Task](https://webjs.dev/ui/docs/ai-elements/task) for more examples.

## Commit

A commit is a collapsible row with a line for each changed file. Say what changed in the title, Added, Edited or Deleted, and put the line counts in the description. Each file opens its diff in a Sheet.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import {
  codeBlockClass, codeBlockContentClass, codeBlockCodeClass, codeBlockLineClass,
  type CodeBlockLineVariant,
} from '#components/ui/code-block.ts';
import {
  sheetHeaderClass, sheetTitleClass, sheetDescriptionClass,
} from '#components/ui/sheet.ts';
import {
  traceClass, traceLineClass, traceIconClass, traceTitleClass, traceDescriptionClass,
  traceCollapsibleClass, traceCollapsibleTriggerClass, traceCollapsibleContentClass,
} from '#components/ui/trace.ts';
import {
  ChevronRightIcon, FilePenIcon, FilePlusIcon, GitCommitHorizontalIcon,
} from '#lib/ui/lucide.ts';

const files = [
  {
    path: 'app/login/page.tsx',
    added: false,
    additions: 2,
    deletions: 2,
    diff: [
      '@@ -14,7 +14,7 @@ export default async function LoginPage({',
      '   searchParams,',
      ' }) {',
      '   const { next } = await searchParams',
      '-  const redirectTo =',
      '-    next && next.startsWith("/") ? next : "/"',
      '+  const redirectTo = safeRedirect(next)',
      '+',
      '   return <LoginForm redirectTo={redirectTo} />',
      ' }',
    ].join('\n'),
  },
  {
    path: 'lib/auth/redirect.ts',
    added: true,
    additions: 7,
    deletions: 0,
    diff: [
      '@@ -0,0 +1,7 @@',
      '+export function safeRedirect(next: string | undefined) {',
      '+  if (!next || !next.startsWith("/") || next.startsWith("//")) {',
      '+    return "/"',
      '+  }',
      '+',
      '+  return next',
      '+}',
    ].join('\n'),
  },
];

function line(text: string, variant: CodeBlockLineVariant, extra = '') {
  // An empty line holds a newline, so copying a selection keeps blank lines.
  return html`<span data-slot="code-block-line" data-variant=${variant} class=${cn(codeBlockLineClass({ variant }), extra)}><span data-slot="code-block-line-content" class="min-w-0">${text === '' ? String.fromCharCode(10) : text}</span></span>`;
}

function DiffLines(diff: string) {
  return diff.split('\n').map((text) => {
    if (text.startsWith('@@')) return line(text, 'default', 'text-muted-foreground');
    const variant = text.startsWith('+') ? 'added' : text.startsWith('-') ? 'removed' : 'default';
    return line(text.slice(1), variant);
  });
}

// Each file is a sheet whose trigger wraps the file's line.
export default function TraceCommit() {
  return html`
    <div data-slot="trace" class=${cn(traceClass(), 'max-w-sm')}>
      <details data-slot="trace-collapsible" open class=${cn(traceCollapsibleClass(), 'group/trace-collapsible')}>
        <summary data-slot="trace-collapsible-trigger" class=${traceCollapsibleTriggerClass()}>
          <span data-slot="trace-line" class=${traceLineClass()}>
            <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${GitCommitHorizontalIcon()}</span>
            <span data-slot="trace-title" class=${traceTitleClass()}>Committed a1b2c3: Fix the login redirect</span>
          </span>
          <span data-slot="trace-icon" aria-hidden="true" class=${cn(traceIconClass(), 'transition-transform group-open/trace-collapsible:rotate-90')}>${ChevronRightIcon()}</span>
        </summary>
        <div data-slot="trace-collapsible-content" class=${traceCollapsibleContentClass()}>
          <div data-slot="trace" class=${traceClass()}>
            ${files.map((file) => html`
              <ui-sheet>
                <ui-sheet-trigger>
                  <button type="button" class="flex w-fit max-w-full min-w-0 text-start outline-none">
                    <span data-slot="trace-line" class=${traceLineClass()}>
                      <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${file.added ? FilePlusIcon() : FilePenIcon()}</span>
                      <span data-slot="trace-title" class=${traceTitleClass()}>${file.added ? 'Added' : 'Edited'} ${file.path}</span>
                      <span data-slot="trace-description" class=${cn(traceDescriptionClass(), 'font-mono')}>+${file.additions} −${file.deletions}</span>
                      <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${ChevronRightIcon()}</span>
                    </span>
                  </button>
                </ui-sheet-trigger>
                <ui-sheet-content side="right">
                  <div data-slot="sheet-header" class=${sheetHeaderClass()}>
                    <h2 data-slot="sheet-title" class=${cn(sheetTitleClass(), 'font-mono')}>${file.path}</h2>
                    <p data-slot="sheet-description" class=${sheetDescriptionClass()}>
                      ${file.additions} additions, ${file.deletions} deletions
                    </p>
                  </div>
                  <div data-slot="code-block" data-variant="default" data-size="default" class=${cn(codeBlockClass(), 'mx-6 mb-6 w-auto')}>
                    <pre data-slot="code-block-content" tabindex="0" dir="ltr" style="counter-reset: line 0" class=${codeBlockContentClass()}><code data-slot="code-block-code" class=${codeBlockCodeClass()}>${DiffLines(file.diff)}</code></pre>
                  </div>
                </ui-sheet-content>
              </ui-sheet>
            `)}
          </div>
        </div>
      </details>
    </div>
  `;
}
```

## Whole Turn

Three levels: the turn, a summary, and the rows. Text between steps sits between two traces.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import {
  codeBlockClass, codeBlockContentClass, codeBlockCodeClass,
} from '#components/ui/code-block.ts';
import {
  traceClass, traceLineClass, traceIconClass, traceTitleClass, traceDescriptionClass,
  traceCollapsibleClass, traceCollapsibleTriggerClass, traceCollapsibleContentClass,
} from '#components/ui/trace.ts';
import {
  BrainIcon, ChevronRightIcon, FileTextIcon, TerminalIcon,
} from '#lib/ui/lucide.ts';

// A collapsible row: a details element whose summary holds the line, and a
// chevron that turns while it is open.
function TraceCollapsible(line: unknown, content: unknown, open = false) {
  return html`
    <details data-slot="trace-collapsible" ?open=${open} class=${cn(traceCollapsibleClass(), 'group/trace-collapsible')}>
      <summary data-slot="trace-collapsible-trigger" class=${traceCollapsibleTriggerClass()}>
        ${line}
        <span data-slot="trace-icon" aria-hidden="true" class=${cn(traceIconClass(), 'transition-transform group-open/trace-collapsible:rotate-90')}>${ChevronRightIcon()}</span>
      </summary>
      ${content}
    </details>
  `;
}

export default function TraceTurn() {
  return html`
    <div class="w-full max-w-sm">
      ${TraceCollapsible(
        html`<span data-slot="trace-line" data-status="error" class=${traceLineClass()}>
          <span data-slot="trace-title" class=${traceTitleClass()}>Worked for 2m 4s, 1 command failed</span>
        </span>`,
        html`<div data-slot="trace-collapsible-content" class=${cn(traceCollapsibleContentClass(), 'flex flex-col gap-2')}>
          <div data-slot="trace" class=${traceClass()}>
            ${TraceCollapsible(
              html`<span data-slot="trace-line" class=${traceLineClass()}>
                <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${BrainIcon()}</span>
                <span data-slot="trace-title" class=${traceTitleClass()}>Thought</span>
                <span data-slot="trace-description" class=${traceDescriptionClass()}>12s</span>
              </span>`,
              html`<div data-slot="trace-collapsible-content" class=${cn(traceCollapsibleContentClass(), 'whitespace-pre-wrap')}>I should check which package managers are installed before I scaffold anything.</div>`,
            )}
            ${TraceCollapsible(
              html`<span data-slot="trace-line" data-status="error" class=${traceLineClass()}>
                <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${TerminalIcon()}</span>
                <span data-slot="trace-title" class=${traceTitleClass()}>Ran 2 commands, 1 failed</span>
              </span>`,
              html`<div data-slot="trace-collapsible-content" class=${traceCollapsibleContentClass()}>
                <div data-slot="trace" class=${traceClass()}>
                  <span data-slot="trace-line" class=${traceLineClass()}>
                    <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${TerminalIcon()}</span>
                    <span data-slot="trace-title" class=${traceTitleClass()}>Ran node --version</span>
                  </span>
                  ${TraceCollapsible(
                    html`<span data-slot="trace-line" data-status="error" class=${traceLineClass()}>
                      <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${TerminalIcon()}</span>
                      <span data-slot="trace-title" class=${traceTitleClass()}>Failed to run pnpm --version</span>
                    </span>`,
                    html`<div data-slot="trace-collapsible-content" class=${traceCollapsibleContentClass()}>
                      <div data-slot="code-block" data-variant="destructive" data-size="sm" class=${codeBlockClass({ variant: 'destructive' })}>
                        <pre data-slot="code-block-content" data-wrap tabindex="0" dir="ltr" style="counter-reset: line 0" class=${cn(codeBlockContentClass(), 'max-h-64')}><code data-slot="code-block-code" class=${codeBlockCodeClass()}>command not found: pnpm</code></pre>
                      </div>
                    </div>`,
                  )}
                </div>
              </div>`,
              true,
            )}
          </div>
          <p>Node is installed and pnpm is not. Reading the docs config.</p>
          <div data-slot="trace" class=${traceClass()}>
            <a href="#turn">
              <span data-slot="trace-line" class=${traceLineClass()}>
                <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${FileTextIcon()}</span>
                <span data-slot="trace-title" class=${traceTitleClass()}>Read apps/v4/lib/docs.ts</span>
                <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${ChevronRightIcon()}</span>
              </span>
            </a>
          </div>
        </div>`,
        true,
      )}
    </div>
  `;
}
```

## Reasoning

Render a `reasoning` part from the AI SDK. The row is a plain trace line until the first text arrives. See Open State.

```ts
import { html, nothing } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { bubbleClass, bubbleContentClass } from '#components/ui/bubble.ts';
import { buttonClass } from '#components/ui/button.ts';
import { messageClass, messageContentClass } from '#components/ui/message.ts';
import {
  traceClass, traceLineClass, traceIconClass, traceTitleClass,
  traceCollapsibleClass, traceCollapsibleTriggerClass, traceCollapsibleContentClass,
} from '#components/ui/trace.ts';
import { BrainIcon, ChevronRightIcon } from '#lib/ui/lucide.ts';

const question = 'Why is the checkout deploy so slow?';
const reasoning =
  'The build log shows install and compile finish in under a minute. Image optimization takes almost four, and it reruns on every deploy because the cache key includes the commit hash.';
const answer =
  'Image optimization is the bottleneck. Key its cache on the lockfile and the image directory instead of the commit hash.';

// A reasoning row. While it streams (running) the line shimmers and the row
// is open; once it settles it reads "Thought" and closes. With no text yet it
// is a plain line, since there is nothing to expand.
function ThinkingTrace(text: string, running: boolean) {
  const line = html`<span data-slot="trace-line" data-status=${running ? 'running' : nothing} class=${traceLineClass()}>
    <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${BrainIcon()}</span>
    <span data-slot="trace-title" class=${traceTitleClass()}>${running ? 'Thinking' : 'Thought'}</span>
  </span>`;
  if (text.length === 0) return line;
  return html`
    <details data-slot="trace-collapsible" ?open=${running} class=${cn(traceCollapsibleClass(), 'group/trace-collapsible')}>
      <summary data-slot="trace-collapsible-trigger" class=${traceCollapsibleTriggerClass()}>
        ${line}
        <span data-slot="trace-icon" aria-hidden="true" class=${cn(traceIconClass(), 'transition-transform group-open/trace-collapsible:rotate-90')}>${ChevronRightIcon()}</span>
      </summary>
      <div data-slot="trace-collapsible-content" class=${cn(traceCollapsibleContentClass(), 'whitespace-pre-wrap')}>${text}</div>
    </details>
  `;
}

// The conversation once the reply has finished streaming.
export default function TraceThinking() {
  return html`
    <div class="flex min-h-72 w-full max-w-sm flex-col gap-4 py-6 text-sm">
      <div data-slot="message" data-align="end" class=${messageClass()}>
        <div data-slot="message-content" class=${messageContentClass()}>
          <div data-slot="bubble" data-variant="muted" data-align="end" class=${bubbleClass({ variant: 'muted' })}>
            <div data-slot="bubble-content" class=${bubbleContentClass()}>${question}</div>
          </div>
        </div>
      </div>
      <div data-slot="message" data-align="start" class=${messageClass()}>
        <div data-slot="message-content" class=${cn(messageContentClass(), 'gap-4')}>
          <div data-slot="trace" class=${traceClass()}>
            ${ThinkingTrace(reasoning, false)}
          </div>
          <p>${answer}</p>
        </div>
      </div>
      <button type="button" data-slot="button" data-variant="outline" data-size="sm" class=${cn(buttonClass({ variant: 'outline', size: 'sm' }), 'mt-auto self-start')}>
        Reset
      </button>
    </div>
  `;
}
```

See [Reasoning](https://webjs.dev/ui/docs/ai-elements/reasoning) for more examples.

## Tool

Render tool parts from the AI SDK. Map the tool part as in [Tool](https://webjs.dev/ui/docs/ai-elements/tool#states).

```ts
import { html, nothing } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { bubbleClass, bubbleContentClass } from '#components/ui/bubble.ts';
import { buttonClass } from '#components/ui/button.ts';
import {
  codeBlockClass, codeBlockContentClass, codeBlockCodeClass,
} from '#components/ui/code-block.ts';
import { messageClass, messageContentClass } from '#components/ui/message.ts';
import {
  traceClass, traceLineClass, traceIconClass, traceTitleClass,
  traceCollapsibleClass, traceCollapsibleTriggerClass, traceCollapsibleContentClass,
} from '#components/ui/trace.ts';
import { ChevronRightIcon, TerminalIcon } from '#lib/ui/lucide.ts';

const question = 'Which package managers are installed?';
const answer = 'Node 24 and npm 11 are installed. pnpm is not.';

type ToolPart =
  | { state: 'output-available'; command: string; stdout: string }
  | { state: 'output-error'; command: string; errorText: string }
  | { state: 'output-denied'; command: string }
  | { state: 'input-available'; command: string };

const tools: ToolPart[] = [
  { state: 'output-available', command: 'node --version', stdout: 'v24.18.0' },
  { state: 'output-available', command: 'npm --version', stdout: '11.6.2' },
  { state: 'output-error', command: 'pnpm --version', errorText: 'command not found: pnpm' },
];

// One tool part as a row: a finished call expands to its output, a denied
// call is a plain line, and a call with no output is running while the reply
// streams and failed once it has stopped.
function ToolTrace(part: ToolPart, live: boolean) {
  if (part.state === 'output-available' || part.state === 'output-error') {
    const failed = part.state === 'output-error';
    return html`
      <details data-slot="trace-collapsible" class=${cn(traceCollapsibleClass(), 'group/trace-collapsible')}>
        <summary data-slot="trace-collapsible-trigger" class=${traceCollapsibleTriggerClass()}>
          <span data-slot="trace-line" data-status=${failed ? 'error' : nothing} class=${traceLineClass()}>
            <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${TerminalIcon()}</span>
            <span data-slot="trace-title" class=${traceTitleClass()}>${failed ? 'Failed to run' : 'Ran'} ${part.command}</span>
          </span>
          <span data-slot="trace-icon" aria-hidden="true" class=${cn(traceIconClass(), 'transition-transform group-open/trace-collapsible:rotate-90')}>${ChevronRightIcon()}</span>
        </summary>
        <div data-slot="trace-collapsible-content" class=${traceCollapsibleContentClass()}>
          <div data-slot="code-block" data-variant="default" data-size="sm" class=${codeBlockClass()}>
            <pre data-slot="code-block-content" data-wrap tabindex="0" dir="ltr" style="counter-reset: line 0" class=${cn(codeBlockContentClass(), 'max-h-64')}><code data-slot="code-block-code" class=${codeBlockCodeClass()}>${failed ? part.errorText : part.stdout}</code></pre>
          </div>
        </div>
      </details>
    `;
  }
  if (part.state === 'output-denied') {
    return html`<span data-slot="trace-line" class=${traceLineClass()}>
      <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${TerminalIcon()}</span>
      <span data-slot="trace-title" class=${traceTitleClass()}>Denied ${part.command}</span>
    </span>`;
  }
  return html`<span data-slot="trace-line" data-status=${live ? 'running' : 'error'} class=${traceLineClass()}>
    <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${TerminalIcon()}</span>
    <span data-slot="trace-title" class=${traceTitleClass()}>${live ? 'Running' : 'Failed to run'} ${part.command}</span>
  </span>`;
}

// The conversation once the reply has finished streaming.
export default function TraceToolCalls() {
  return html`
    <div class="flex min-h-72 w-full max-w-sm flex-col gap-4 py-6 text-sm">
      <div data-slot="message" data-align="end" class=${messageClass()}>
        <div data-slot="message-content" class=${messageContentClass()}>
          <div data-slot="bubble" data-variant="muted" data-align="end" class=${bubbleClass({ variant: 'muted' })}>
            <div data-slot="bubble-content" class=${bubbleContentClass()}>${question}</div>
          </div>
        </div>
      </div>
      <div data-slot="message" data-align="start" class=${messageClass()}>
        <div data-slot="message-content" class=${cn(messageContentClass(), 'gap-4')}>
          <div data-slot="trace" class=${traceClass()}>
            ${tools.map((part) => ToolTrace(part, false))}
          </div>
          <p>${answer}</p>
        </div>
      </div>
      <button type="button" data-slot="button" data-variant="outline" data-size="sm" class=${cn(buttonClass({ variant: 'outline', size: 'sm' }), 'mt-auto self-start')}>
        Reset
      </button>
    </div>
  `;
}
```

See [Tool](https://webjs.dev/ui/docs/ai-elements/tool) for more examples.

## Accessibility

A trace adds no roles of its own. Each line gets its semantics from the element that wraps it.

- A trace line on its own is a `span`. It is read as text and is not a tab stop.
- Put it in the `<summary>` of a `<details>` and the browser exposes it as a disclosure that reports whether it is expanded. Wrap it in a link, or in the button inside a dialog or sheet trigger, and it takes the keyboard and focus behavior of that element.
- Mark each trace icon `aria-hidden="true"`, so the title is the accessible name. Write it as a sentence that says what happened, like "Edited trace.tsx", not just "trace.tsx".
- When a link opens a new tab, add "(opens in a new tab)" to the title with `sr-only`.
- Status is shown with color and motion, so put it in the title too. Write "Running pnpm build" while it runs and "Failed to run pnpm build" when it errors.
- The shimmer on a running title stops when the reader prefers reduced motion. The title still says what is happening.
- Inside a [Message Scroller](https://webjs.dev/ui/docs/components/message-scroller), each line is announced once when it is added.
- The collapsible content mutes its text. If you put a block with a muted background inside it, give the block `text-foreground` so it keeps its contrast. A code block sets its own text color.

## API Reference

Trace is a set of class helpers. Each part is a plain element carrying the helper's classes and its `data-slot`, and every helper's classes merge with yours through `cn()`.

### traceClass

A list of rows, on a `div` with `data-slot="trace"`. It also styles any trigger or link that wraps a trace line.

### traceLineClass

One line: an icon and a title, on a `span` with `data-slot="trace-line"`. It is not a button or a tab stop. Wrap it in a trigger or a link to make it do something.

| Attribute | Type | Default |
| --- | --- | --- |
| `data-status` | `"running" \| "error" \| "pending"` | none |

### traceIconClass

An icon slot, on a `span` with `data-slot="trace-icon"` and `aria-hidden="true"`. Before the title it names the action; after it, it is the indicator.

### traceTitleClass

One sentence on one line, on a `span` with `data-slot="trace-title"`. It truncates and shimmers while the line is running.

### traceDescriptionClass

Secondary text after the title, such as a count or a duration, on a `span` with `data-slot="trace-description"`. It does not truncate.

### traceCollapsibleClass

A row that expands, on a `<details>` with `data-slot="trace-collapsible"`. Add `group/trace-collapsible` to turn the chevron while it is open.

| Attribute | Type | Default |
| --- | --- | --- |
| `open` | `boolean` | `false` |

### traceCollapsibleTriggerClass

The trigger that opens and closes the row, on its `<summary>` with `data-slot="trace-collapsible-trigger"`. Put a trace line inside it, then a chevron icon after the line.

### traceCollapsibleContentClass

The detail of a row that expands, on a `div` with `data-slot="trace-collapsible-content"` after the summary.
