Trace
Displays the steps an agent takes, such as reasoning, tool calls and sources, as a list of lines.
The formatter uses the machine's time zone, so in UTC an evening event moves to the next day. Pass the event's time zone to Intl.DateTimeFormat and the test passes in CI too.
Trace renders a stack of lines. A line holds an icon and a title, and can
also carry a description and a status. A line can open to reveal more detail,
act as a link, or be the trigger of a dialog or sheet. Every line has the same
shape, so reasoning, tool calls, sources and plans built from it look and
behave the same.
Use it for the steps an agent takes, such as calling a tool, running a subagent or editing a file. Use Marker for notes and dividers between turns.
Installation
Needs the arene setup first. Also adds Collapsible.
Install the packages it imports:
Set up the token layer and the StyleX compiler, if you have not already. See
Installation, and paste state-styles.ts from the same
page. The trace also needs interop.css, which sizes the icons inside a line.
Install Collapsible, which an expanding line is built on, and Shimmer, which sweeps the title of a running line.
Paste this source into the file named in its title.
Change the @/ imports if your project uses different aliases.
Usage
For a line that reveals detail when it opens, wrap it in a TraceCollapsible:
Composition
A line that expands:
TraceLine is always the line. To make it a link or open a dialog, render it
as that element with render. A line rendered as an a or a button shows a
pointer, lights up on hover and shows a ring on keyboard focus:
To make it expand, wrap it in TraceCollapsibleTrigger, which styles itself
and adds the chevron.
Line
A TraceLine on its own is a step with no detail to show. It reads as plain
text and does not change on hover.
Status
Set status on TraceLine when a step is running, has failed or has not
started yet.
| Status | Marks |
|---|---|
| none | Finished work, such as "Ran npm ci". |
"error" | Failed work. The title names the failure, as in "Error running tsc --noEmit". |
"running" | Work under way, titled in the present tense, as in "Running npx vitest". |
"pending" | Work not yet started, such as a step in a plan: "Run git push". |
An error line turns destructive and keeps that colour on hover. A pending line
is dimmed. A running line sweeps its title with
shimmerStyles.base. The icon is yours to choose;
the examples use a Spinner while a step runs.
Description
A TraceDescription placed after the TraceTitle holds secondary text, such
as a diff stat, a duration or a count. It is set in the mono face at the
metadata size, and it does not truncate: the title gives way first.
Collapsible
A line wrapped in a TraceCollapsible reveals more detail when it opens. The
TraceLine goes inside TraceCollapsibleTrigger, and the detail goes in
TraceCollapsibleContent. The trigger adds a chevron to the end of the line,
which turns when the row opens, and the content hangs under the title behind a
hairline guide.
TraceCollapsibleContent mutes its text. A block with its own surface keeps
its own colour: a Code Block sets the foreground
colour on its panel, so the output in the examples is not muted.
Open state
Rows start closed. Pass defaultOpen to TraceCollapsible for a row that
starts open, or pair open with onOpenChange to control it.
To keep a row open while it streams, unless the reader has toggled it, pass
open ?? running. The thinking row in the demo at the top of the page does
this: it opens while the reasoning streams in and closes when it ends, unless
the reader has opened or closed it themselves.
Link
Render the TraceLine as an anchor, or as your router's link component. For a
new tab, end the line with an arrow-up-right icon and add "(opens in a new tab)"
to the title, visually hidden with states.srOnly.
Dialog
Render the TraceLine as the Dialog's trigger. The
dialog handles its open state, Escape and returning focus. The trigger goes in
the line's render, not the other way round: a trigger expects to render a
native button, and the line is a span by default.
Sheet
The same shape as the dialog, with a Sheet. A Drawer or Popover works the same way.
Group
Put lines that sit next to each other in a Trace. It stacks them with a
small gap and gives every row the full width to truncate in.
Sources
A collapsible row whose content is a Trace of link lines, one per
source the agent read.
Nesting
A row's content can hold another Trace, so a summary expands into steps and a
step into its output. Derive the parent's title and status from the rows
inside it. Pass keepMounted to a TraceCollapsibleContent that holds rows, so
the rows inside keep their open state while the parent is closed.
Whole turn
A full turn nests three levels: the turn, a summary, then the rows. Prose that
falls between steps goes between two Trace lists.
Accessibility
Trace does not add any roles. A line takes its semantics from whatever
element wraps it.
- Outside any wrapper, a
TraceLinerenders aspan. Screen readers read it as plain text, and keyboard focus skips it. - Inside a
TraceCollapsibleTriggerit is the content of a button witharia-expanded. Rendered as a link, or as the trigger of a dialog or sheet, it is that element, with its keyboard and focus behaviour. TraceIconis hidden from assistive technology, soTraceTitleis the accessible name. Write it as a sentence that says what happened, such as "Edited format-date.ts", not just "format-date.ts".- Status is shown with colour and motion, so put it in the title too: "Running tsc --noEmit" while it runs, "Error running tsc --noEmit" when it fails.
- For a line that changes from running to done while it streams, pass
role="status"to the line, so assistive technology announces the new title. The line has to stay mounted, because a live region announces changes inside it, not a region that replaces it, and it cannot sit in a trigger, whose content is the button's name. Leave the role off theTrace: a status region is read whole on every change, so when its rows stream detail, like the reasoning in the demo at the top of the page, each chunk reads the list again. Inside a Message Scroller, the transcript's log announces each row when it is added. - When the reader prefers reduced motion, a running title does not shimmer. Its text still describes the work in progress.
API reference
Pass render to replace a part's element or compose it with another component.
Every part also takes xstyle and className. Trace, TraceLine,
TraceIcon, TraceTitle and TraceDescription take style as real inline
CSS, merged over the compiled styles.
Trace
A div that stacks its rows.
TraceLine
One line: icons, a title and a description. It is a span, so it is not a
button or a tab stop until render makes it an a or a button.
| Prop | Type | Default |
|---|---|---|
status | "running" | "error" | "pending" | — |
TraceIcon
A decorative icon slot, hidden from assistive technology. Before the title it names the action; after it, it is the indicator, and it sits closer to the text before it.
TraceTitle
One sentence on one line. It truncates, and it shimmers while its line is running.
TraceDescription
Text that follows the title, such as a duration or a count. It does not truncate.
TraceCollapsible
A row that expands. It wraps Collapsible and accepts its props.
| Prop | Type | Default |
|---|---|---|
open | boolean | — |
defaultOpen | boolean | false |
onOpenChange | (open: boolean, details) => void | — |
TraceCollapsibleTrigger
The button that toggles the row. Put a TraceLine inside it; the line
adds the chevron. It wraps CollapsibleTrigger and accepts its props.
TraceCollapsibleContent
The panel an expanding row reveals. It wraps CollapsibleContent and accepts
its props.
| Prop | Type | Default |
|---|---|---|
keepMounted | boolean | false |
xstyle and className apply to the inner element that draws the guide line,
and style to the animated panel.
traceStyles
The style map behind the component, exported so you can apply the same styles to any element.
| Key | Description |
|---|---|
base | The stacked list |
line | The row: icon gap, type, the muted colour, link and button styles |
statuses | One entry per status, keyed by its name |
icon | The icon slot |
title | The truncating title |
description | The mono metadata after the title |
content | The indented, guide-lined detail of an expanding row |
Data attributes
| Attribute | On | Effect |
|---|---|---|
data-slot="trace" | the root | Targets the list |
data-slot="trace-line" | the line | Targets a line |
data-status | the line | Reflects the status prop |
data-slot="trace-icon" | the icon slot | Targets an icon |
data-slot="trace-title" | the title | Targets the title |
data-slot="trace-description" | the description | Targets the description |
data-slot="trace-collapsible" | an expanding row | Targets the row |
data-slot="trace-collapsible-trigger" | its trigger | Targets the button |
data-slot="trace-collapsible-content" | its animated panel | Targets the panel |
data-slot="trace-collapsible-content-inner" | the guide-lined box | Targets the detail |
CSS variables
| Variable | On | Effect |
|---|---|---|
--arene-icon-size | the root | The icon size, 1rem. The guide under an expanding row follows the icon's centre |
Set it with style on Trace, or on a TraceCollapsible to resize one row.
Cast the object to CSSProperties, as Sidebar
does. xstyle rejects a StyleX entry that sets only custom properties.