# `lr-trace-tree` - **Import** `import '@aceshooting/lyra-ui/components/lr-trace-tree.js';` (stable tag alias; registers the tag) - **Class** `LyraTraceTree`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/trace-tree/trace-tree.class.js` - **Family** `components/agent-tools/` — see `llms/index.md` for its siblings - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md` - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [llms-full.txt](../../llms-full.txt) - **Deprecations** none - **Optional peers** none - **Themeable via** 17 parts, 11 custom properties — see this component's own `@csspart`/`@cssprop` list below - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md` --- ## `lr-trace-tree` A collapsible span hierarchy for one agent/LLM trace (Langfuse/LangSmith run-tree style): kind icon, name, status, an inline duration bar on the shared trace time scale, and optional tokens/cost columns. Consumes the same `LyraSpan[]` as ``. Span views omit whitespace-only IDs and preserve every nonblank business ID exactly, including surrounding whitespace. The first valid admitted duplicate continues to win. **Properties:** `spans: LyraSpan[] = []` (attribute: false) — the same `LyraSpan` shape documented under `lr-span-waterfall` above (exported from `trace-tree/span.ts`); hierarchy comes from `parentId`, and a span whose `parentId` is missing or doesn't resolve within the same array renders as a root rather than being dropped. Duration bars scale to the whole trace, measured before the shared 500-span cap is applied, so a truncated tail never stretches the surviving bars across their tracks. `activeSpanId: string | null = null` (attribute `active-span-id`), `label?: string`, `showTokens: boolean = false` (attribute `show-tokens`) — surfaces `tokensIn`/`tokensOut`, `showCost: boolean = false` (attribute `show-cost`) — surfaces `costText`, and `hideBars: boolean = false` (attribute `hide-bars`). `label` is an optional accessible-name override for the `role="tree"` element: omission localizes the default, and any supplied string — including `''` — is rendered verbatim. Token counts render only when finite and non-negative; invalid metrics are omitted rather than reaching `Intl.NumberFormat`. A row's accessible name includes its optional `detail` text as well as its name/status/metrics, and updates when the supplied span data changes. Every trace view uses the same bounded runtime projection: provider records are normalized with deterministic first-wins identity, then at most 500 mount. The controlled `activeSpanId` and its resolvable ancestor path reserve positions before ordinary input-order spans. Non-object records, empty/blank ids, non-finite starts/ends, and later duplicate ids are omitted; negative starts clamp to zero, ends clamp to at least their start, unknown kinds become `other`, and unknown statuses become `pending`. A localized `[part="limit"]` note exposes truncation. **Methods:** `expandAll()` and `collapseAll()` set every row's expanded state at once. **Events:** `lr-span-select` (`detail: { spanId: string }`, a row was activated) and `lr-span-toggle` (`detail: { spanId: string; expanded: boolean }`, a row was expanded or collapsed). **CSS parts:** `base` (`role="tree"`), `header` (the column-header row, only when `showTokens`/`showCost`), `row` (`role="treeitem"`), `toggle`, `icon`, `name`, `detail`, `status-text`, `duration`, `tokens-in`, `tokens-out` (when `showTokens`), `cost` (when `showCost`), `bar-track`, `bar`, `empty` (shown when `spans` is empty), `limit` (the 500-span projection notice), and `live-region`. **Themeable custom properties:** `--lr-trace-tree-row-active-bg` (default `var(--lr-color-brand-quiet)`) — the background of the active (`activeSpanId`) row — and `--lr-trace-tree-row-active-color` (default `var(--lr-color-text)`) — the color of that row's secondary text (`detail`, `duration`, `tokens-in`, `tokens-out`, `cost`, and the `pending` `status-text` label). Same state-scoped-property convention described under `lr-span-waterfall` above: an inline `var()` fallback rather than a `:host` declaration, so either can be set on the element or any ancestor, and they exist because `::part(row)[data-active]` is invalid CSS. `--lr-trace-tree-max-indent` (default `var(--lr-size-12rem)`) caps visual nesting indentation; semantic `aria-level` remains exact at deeper levels. **Contrast note:** the active row is more than a tint. Its secondary text would sit at ~4.25:1 against the default tint if it stayed at `--lr-color-text-quiet`, so it rises to full-strength `--lr-color-text` while the row is active, and the semantic `status-text` labels are rendered as `color-mix(in srgb, var(--lr-color-) 75%, var(--lr-color-text))` — keeping the status hue (an error row stays red) while clearing the 4.5:1 floor (success 4.46 → 6.18, `denied` 4.28 → 5.96). Both adjustments are theme-symmetric, because `--lr-color-text` flips with the color scheme. `[part='bar']` is deliberately untouched: it is a non-text graphic on a 3:1 floor, and its saturation is the row's primary status signal. The two properties are a **pair**. The defaults assume the active background stays on the same side of the lightness midpoint as the ambient surface, so a consumer who sets `--lr-trace-tree-row-active-bg` to a dark tint in light mode (or a light one in dark mode) must set `--lr-trace-tree-row-active-color` to match, and should re-check the status-label tones against the new tint as well. **Additional API surface:** - `--lr-trace-tree-toggle-hover-bg` — Toggle hover background. Default: `var(--lr-color-brand-quiet)`. - `--lr-trace-tree-success-color` — Success status text and bar. Default: `var(--lr-color-success)`. - `--lr-trace-tree-error-color` — Error status text and bar. Default: `var(--lr-color-danger)`. - `--lr-trace-tree-denied-color` — Denied status text and bar. Default: `var(--lr-color-warning)`. - `--lr-trace-tree-running-color` — Running status text and stripe. Default: `var(--lr-color-brand)`. - `--lr-trace-tree-pending-color` — Pending status text and bar. Default: `var(--lr-color-text-quiet)`. - `--lr-trace-tree-bar-track-bg` — Duration bar track. Default: `var(--lr-color-surface-raised)`. - `--lr-trace-tree-running-stripe-bg` — Running stripe contrast. Default: `var(--lr-color-brand-quiet)`.