# `lr-retrieval-trace` - **Import** `import '@aceshooting/lyra-ui/components/lr-retrieval-trace.js';` (stable tag alias; registers the tag) - **Class** `LyraRetrievalTrace`, also available unregistered from `@aceshooting/lyra-ui/components/retrieval/retrieval-trace/retrieval-trace.class.js` - **Family** `components/retrieval/` — 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** 13 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-retrieval-trace` A retrieval pipeline's stage timeline (query rewriting, embedding, retrieval, reranking, filtering) rendered through `lr-span-waterfall`, plus a disclosure list exposing each stage's evidence. Never fetches, ranks, or computes retrieval results itself. **Properties:** - `stages: RetrievalStage[] = []` (attribute: false) — `RetrievalStage { id: string; kind: RetrievalStageKind; label?: string; startMs: number; endMs?: number; status: 'pending' | 'running' | 'success' | 'error' | 'denied'; detail?: string; evidence?: RetrievalStageEvidence }` (exported here), where `RetrievalStageKind = 'query-rewrite' | 'embed' | 'retrieve' | 'rerank' | 'filter'`. `startMs`/`endMs` are milliseconds relative to the trace start (`endMs` absent while still running); `status` uses `LyraSpan.status`'s vocabulary verbatim; `label` overrides the localized default label for `kind`; `detail` is secondary text under the stage name. Pass in any order — the timeline sorts by `startMs`. Each stage projects to one `LyraSpan` with `kind` mapped `query-rewrite → 'llm'`, `embed → 'embedding'`, `retrieve → 'retriever'`, `rerank`/`filter` → `'tool'`. Without a `label` override, an unknown runtime kind keeps its literal string as the visible label and uses the generic `'tool'` span kind instead of aborting the trace. Stage ids must be nonempty, nonblank, and unique: invalid records and later duplicates are omitted first-wins before timeline, evidence, controlled state, counts, or event paths - `RetrievalStageEvidence { text?: string; chunks?: RetrievalChunk[]; metadata?: Record }` — `chunks` is **`RetrievalChunk` from `@aceshooting/lyra-ui/ai`** verbatim, rendered through `lr-chunk-inspector` (`source.id → sourceId`, `source.name → title`, `locator → anchor`; page locators also supply the visible `page`); `text` is free-form (e.g. the rewritten query, an embedding model id); `metadata` renders as a plain key/value list. Malformed runtime chunk rows are omitted while valid neighboring chunks remain visible. A stage whose evidence has none of the three renders no disclosure row at all - `activeStageId: string | null = null` (attribute `active-stage-id`) — controlled selection, forwarded verbatim to the internal `lr-span-waterfall`'s `activeSpanId` - `label: string = ''` — accessible name for the timeline, falling back to its localized default. An authored host `aria-label` independently names the trace and is not cloned onto the timeline; explicit-empty/dynamic host changes preserve that single-owner distinction **Events:** `lr-stage-select` (`detail: { stageId: string }`, a stage's bar was activated — click, Enter, Space), `lr-stage-toggle` (`detail: { stageId: string; expanded: boolean }`, an evidence panel was toggled, either by its own button or implicitly by selecting that stage in the timeline for the first time), and `lr-stage-chunk-action` (`detail: LyraRetrievalTraceChunkActionDetail`, a discriminated `{ stageId, action: 'open', chunkId, sourceId, anchor? } | { stageId, action: 'expand', chunkId, expanded }`). Generic nested chunk events are stopped at the trace boundary so every action has explicit stage identity. **Slots:** none. **CSS parts:** `base`, `timeline` (the internal `lr-span-waterfall`), `evidence-list` (omitted when no stage has evidence), `evidence-row` (omitted for a stage with no evidence), `evidence-toggle`, `evidence-toggle-icon`, `evidence-body` (hidden while collapsed), `evidence-text`, `evidence-metadata` (a `

`), `evidence-metadata-row` (one key/value pair), `evidence-metadata-key` (`

`), `evidence-metadata-value` (`

`), `chunk-inspector` (the stage-owned inspector). **Themeable custom properties:** `--lr-retrieval-trace-active-border` (default `var(--lr-color-brand)`) — the border color of the `[part='evidence-row']` whose stage matches `activeStageId`, leaving every other row on the resting border token. It is an inline `var()` fallback at the point of use rather than a `:host` declaration, so it can be set on the element _or on any ancestor_: `::part(evidence-row)[data-active]` is invalid CSS — Shadow Parts forbids an attribute selector after `::part()` — so marking the active stage previously meant overriding the library-wide `--lr-color-brand` token and repainting every other brand surface with it. Unset, it falls back to that token, so rendering is unchanged. Plus shared tokens otherwise. **Optional peer deps:** none. **Known gotchas:** - Every stage starts collapsed; expansion state is internal `@state` keyed by stage id, not a controlled property.