Reasoning Trace

Demo & usage

More examples

When to use

• Showing a reasoning model's thinking beside its answer, without letting it dominate the thread.
• Debugging why an agent chose one path over another — the reflection steps are usually where it went wrong.
• Giving a reviewer the model's stated confidence per step before they act on the output.
• Rendering a live "thinking" state that resolves into something compact when it completes.

Async states

• loading
• error
• retry
• offline

Item identity & owned state

Restorable state

• openStepIds

Bind these to put a saved view back — the open sections, the hidden columns, the selected rows — and read their Change events to store what the user does.

Outputs

Wire it to your API

This component is headless about transport: it renders what you give it and reports what the user asks for. Nothing below requires @styloviz/data — drive it from whatever you already use.

• This component does not emit a query, so it renders what you give it. Fetch on your own trigger and bind `steps`, `loading` and `error`.
• `connection` reports the state of your `EventSource` or WebSocket. The component cannot infer it: a list that stops growing looks identical whether the feed is quiet or the socket died.
• Normalize failures with `toSvDataError()` from `@styloviz/core`. It derives `retryable` from the status, so a 404 does not get a "Try again" button that can only fail again.

Full walkthrough: Connecting to a backend.

Customization & theming

• `[disclosure]`: `summary` (chip and step titles), `steps` (the model’s narration — the default) or `full` (also each step’s verbatim `raw` provider reasoning). The dangerous field is `raw`: several providers’ terms prohibit displaying the hidden reasoning their models emit, and it is the text most likely to contain a user’s own words repeated back — so it is a field of its own, separate from `content`, and it renders only at `full`, with a dev warning when it actually does.
• The default is `steps`, not `summary`. Defaulting a component whose whole purpose is showing reasoning steps to 'hide the steps' would be a silent breaking change dressed as a safety fix; the thing that needed a safe default was `raw`, which is new and starts hidden.
• `[confidenceBasis]` names what the confidence figure is — 'self-reported by the model', 'mean token logprob'. A per-step confidence with no method behind it is a decorative number on an unverifiable claim: '80%' reads as calibrated when it is usually the model rating its own certainty, which is not comparable across models, prompts or runs. With the meter on and no basis the figure still renders and says 'no method recorded' — hiding a number the host already shows would be a silent regression — and the console says so too.
• The prose here says **reasoning summary**, not 'chain-of-thought', deliberately: the older name invites integrators to pipe a provider’s raw hidden reasoning straight to the DOM. The package name and the `sv-reasoning-trace` selector are unchanged — renaming those would break every host for a wording fix.
• Redaction, from the pack-wide policy (`X-2`): a step's title and body are masked per `provideSvAiPrivacy({ patterns })`, with a note on the step saying something is hidden. Reasoning content quotes the prompt, and the prompt is where the secrets are — a trace is also the thing people screenshot into a bug report.
• `variant` picks the presentation: `inline` for a chip in a thread, `steps` for a numbered list, `streaming` for live output, `nested` for branch connectors.
• `summary` replaces the generated chip text when you want domain wording rather than "Thought for 3.5s · 6 steps".
• `showTiming` and `showConfidence` control the per-step chips; `maxHeight` sets where the list starts scrolling.
• `headingOffset` (default 3) demotes Markdown headings inside a step so a thought cannot hijack the page outline.
• Each step's `kind` selects its glyph — observation, plan, thought, reflection, decision — so the shape of the reasoning is readable at a glance.
• The `summariseTrace` and `flattenSteps` helpers are exported for building your own summary UI over the same model.

Best practices

• Do: Leave `autoCollapse` on inside a conversation. A finished trace that stays open pushes the actual answer off screen — that behaviour is the reason this component exists.
• Do: Use `toggled.automatic` to tell the self-collapse apart from a reader's click, so you only re-scroll the thread on the former.
• Do: Give each step a `title`. The kind label is a fallback, and a list of six steps all reading "Thought" tells the reader nothing.
• Do: Set `status: 'thinking'` on the step currently being written — it keeps that step open and renders the caret on it.
• Don't: Do not use it for executed tool calls. Arguments and results belong in Tool Call Card; a completed run's spans belong in AI Agent Activity Log. This is the model's narration between them.
• Don't: Do not present `confidence` as a probability of being correct. It is the model's self-report, and a confidently wrong step is the most common failure this view exposes.
• Don't: Do not stream raw reasoning to end users in a regulated flow without review — surface it to operators, or gate it behind a toggle.

Accessibility

• The trace is a real disclosure: a `button` with `aria-expanded` and `aria-controls` pointing at the step list, and the same wiring again per step.
• While the model is thinking the region carries `aria-busy="true"` rather than a live region — announcing every token would read the entire monologue aloud.
• Completion is announced once, via a visually-hidden `role="status"` region carrying the summary.
• Status is never colour-only: each step's marker is a distinct glyph — clock, spinner, check or warning triangle.
• The confidence meter is `role="img"` with a spoken label that carries its basis ("Confidence 82% — self-reported by the model", or "— no method recorded"), so it is neither silent to screen readers nor presented to them as a calibrated probability.
• Sub-thought indentation is capped at four levels, so a deep chain stays reachable rather than running off-screen.