# `lr-agent-trace` - **Import** `import '@aceshooting/lyra-ui/components/lr-agent-trace.js';` (stable tag alias; registers the tag) - **Class** `LyraAgentTrace`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/agent-trace/agent-trace.class.js` - **Family** `components/agent-tools/` — see `llms/index.md` for its siblings - **Status** `stable` since `4.1.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** 5 parts, 1 custom property — see this component's own `@csspart`/`@cssprop` list below - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md` --- ## `lr-agent-trace` Provider-neutral agent/LLM trace view combining span-kind filters, handoff quick-jumps, and a hierarchical trace tree from one shared `spans` array. 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 full, unfiltered array; identical contract to `lr-trace-tree.spans` (see `lr-span-waterfall` above for the `LyraSpan` shape). Controlled and never mutated - `activeSpanId: string | null = null` (attribute `active-span-id`) — controlled selection forwarded into the composed `lr-trace-tree`; also updated locally (and re-emitted as `lr-span-select`) when a span is activated from either the tree or the handoff quick-jump list, so it works as a two-way binding - `hiddenKinds: LyraSpan['kind'][] = []` (attribute: false) — span kinds hidden from the tree (`'agent' | 'llm' | 'tool' | 'retriever' | 'embedding' | 'other'`). Empty shows every kind; pre-settable (e.g. to hide `retriever`/`embedding` by default) and readable back after `lr-span-visibility-change` - `label?: string` — forwarded to the composed `lr-trace-tree`. Omission leaves that tree's own `label` unset so it localizes its own default; any supplied string (including `''`) is forwarded verbatim - `showTokens: boolean = false` (attribute `show-tokens`), `showCost: boolean = false` (attribute `show-cost`), `showBars: boolean = true` (attribute `show-bars`, renamed from `hideBars` in 9.0.0 to match the positive polarity of its two siblings above — default inverted so the rendered starting state is unchanged: `el.hideBars = true` becomes `el.showBars = false`) — all forwarded verbatim **Events:** `lr-span-select` (`detail: { spanId: string }`), `lr-span-toggle` (`detail: { spanId: string; expanded: boolean }`), and `lr-span-visibility-change` (`detail: { hiddenKinds: LyraSpan['kind'][] }`). The internal graph legend's generic `lr-visibility-change` event is contained; consumers receive this trace-domain event instead. `spans` is normalized through the same at-most-500-record projection as `` before filtering, handoff lookup, and tree rendering. The controlled active span and its ancestor path reserve positions, and malformed records plus later duplicate ids are omitted, so the composed surfaces cannot disagree. **CSS parts:** `base`, `filter` (the composed `lr-graph-legend` filter row, only rendered while `spans` is non-empty), `handoffs` (the quick-jump list wrapper, only rendered while at least one visible span has `kind: 'agent'`), `handoff` (one entry — a `` wrapping an `lr-handoff-divider`, carrying `data-active`), `tree` (the composed `lr-trace-tree`). **Themeable custom properties:** `--lr-agent-trace-handoff-active-bg` (default `var(--lr-color-brand-quiet)`) — the background of the active (`activeSpanId`) handoff quick-jump entry. Same state-scoped-property convention described under `lr-span-waterfall`: an inline `var()` fallback rather than a `:host` declaration, settable on the element or any ancestor, and it exists because `::part(handoff)[data-active]` is invalid CSS. The composed tree's own `--lr-trace-tree-row-active-bg` and `--lr-trace-tree-row-active-color` are separate knobs and inherit straight through, so restyling both surfaces means setting both — and they carry the pairing caveat documented under `lr-trace-tree` above: the tree's active-row defaults assume the active background stays on the same side of the lightness midpoint as the ambient surface, so a tint that crosses it needs the matching text color set too.