Skip to content
WebJs
Menu

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

Why does pnpm install fail in CI?
Thought for 5s
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.
Ran pnpm --version
10.18.0
Ran git diff --stat HEAD~1 -- package.json pnpm-lock.yaml
 package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Failed to run pnpm install --frozen-lockfile
ERR_PNPM_OUTDATED_LOCKFILE  Cannot install with "frozen-lockfile" because pnpm-lock.yaml is not up to date with package.json
Used 2 sources

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.

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>
  `;
}
View Code

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 for its reply, and Marker for notes and dividers between turns.

Built with Trace

Every pattern below is a composition of trace parts. See AI Elements for examples and code.

PatternShows
Chain of ThoughtA summary that expands into the steps behind it.
PlanThe steps the agent plans to take, and how far it has got.
QueueThe agent's todo list, split into what is left and what is done.
ReasoningThe agent's thinking as it streams.
SourcesThe links the agent used for a reply.
Stack TraceA failed tool call and its stack frames.
SubagentA subagent run, with its tool calls and result.
TaskThe steps the agent takes, as it takes them.
TerminalA command the agent runs, with its output as it streams.
Test ResultsA test run by the agent, with its suites and failures.
ToolA tool call the agent makes, from input to output.

Installation

pnpm dlx @webjsdev/ui add trace

Usage

Use a trace line for a single step:

import {
  traceClass, traceLineClass, traceIconClass, traceTitleClass,
} from '#components/ui/trace.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>:

import {
  traceClass,
  traceCollapsibleClass,
  traceCollapsibleContentClass,
  traceCollapsibleTriggerClass,
  traceIconClass,
  traceLineClass,
  traceTitleClass,
} from '#components/ui/trace.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:

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:

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.

Created branch fix/frozen-lockfile
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>
  `;
}
View Code

Status

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

Ran pnpm install Failed to run pnpm lint Running pnpm build Run pnpm test
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>
  `;
}
View Code
StatusUse for
noneWork 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.

Edited components/settings/notification-preferences-form.tsx +48 −12 Ran pnpm test 14s Searched for useChat 8 results
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>
  `;
}
View Code

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.

Ran node --version
$ node --version
v24.18.0
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>
  `;
}
View Code

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.

Ran node --version
$ node --version
v24.18.0
Ran pnpm --version
$ pnpm --version
10.33.4
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>
  `;
}
View Code

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:

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>`;
  }
}

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)".

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>
  `;
}
View Code
<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.

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>
  `;
}
View Code
<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.

Explored 4 files

Files read while preparing the response.

  • apps/v4/lib/docs.ts
  • apps/v4/lib/components.ts
  • apps/v4/next.config.mjs
  • apps/v4/package.json
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>
  `;
}
View Code

Group

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

Searched for minimumReleaseAge Read pnpm-workspace.yaml Ran pnpm install
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>
  `;
}
View Code

Sources

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

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>
  `;
}
View Code

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

Looking into the slow deploy
Searched for the checkout build log
vercel.com github.com
Read the last twelve deploys
Searching for the cache key
cache key image optimization
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>
  `;
}
View Code

See Chain of Thought and 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.

Committed a1b2c3: Fix the login redirect

app/login/page.tsx

2 additions, 2 deletions

@@ -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} />}

lib/auth/redirect.ts

7 additions, 0 deletions

@@ -0,0 +1,7 @@export function safeRedirect(next: string | undefined) {  if (!next || !next.startsWith("/") || next.startsWith("//")) {    return "/"  }
  return next}
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>
  `;
}
View Code

Whole Turn

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

Worked for 2m 4s, 1 command failed
Thought 12s
I should check which package managers are installed before I scaffold anything.
Ran 2 commands, 1 failed
Ran node --version
Failed to run pnpm --version
command not found: pnpm

Node is installed and pnpm is not. Reading the docs config.

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>
  `;
}
View Code

Reasoning

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

Why is the checkout deploy so slow?
Thought
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.

Image optimization is the bottleneck. Key its cache on the lockfile and the image directory instead of the commit hash.

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>
  `;
}
View Code

See Reasoning for more examples.

Tool

Render tool parts from the AI SDK. Map the tool part as in Tool.

Which package managers are installed?
Ran node --version
v24.18.0
Ran npm --version
11.6.2
Failed to run pnpm --version
command not found: pnpm

Node 24 and npm 11 are installed. pnpm is not.

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>
  `;
}
View Code

See 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, 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.

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

AttributeTypeDefault
openbooleanfalse

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.