@aceshooting/lyra-ui 5.0.0 → 5.2.0

package/llms/components/lr-result-card.md

@@ -0,0 +1,100 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/agent-tools.md — do not edit this file. -->
+
+# `lr-result-card`
+
+- **Import** `import '@aceshooting/lyra-ui/components/agent-tools/result-card/result-card.js';` (registers the tag; side-effect import)
+- **Class** `LyraResultCard`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/result-card/result-card.class.js`
+- **Family** `components/agent-tools/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Documented with** `lr-result-field` (same section below)
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-result-card` / `lr-result-field`
+
+A small, tightly-coupled pair giving any custom `lr-tool-result-view` renderer (registered via
+`registerToolRenderer()` in `../tool-result-view/registry.js`) a consistent "small bordered card +
+label/value row" visual language, without each one hand-rolling its own box. Neither component has
+any code dependency on the tool-result-view registry itself — they're generically usable anywhere a
+small card/field shell is useful.
+
+### `lr-result-card`
+
+A small bordered card shell. Purely visual, with no state of its own beyond slot-presence tracking.
+
+**Properties:**
+- `title: string = ''` — small heading for the card. Leave unset for an untitled card (e.g. a bare
+  block of `lr-result-field` rows with no natural heading).
+- `compact: boolean = false` (reflected) — tighter header/body padding for dense contexts (a card
+  rendered as a row in a transcript or result list), same convention as `<lr-agent-run>`'s own
+  `compact`. Purely a density knob: the border and background stay, so use `appearance="plain"`
+  instead to drop the chrome entirely.
+- `appearance: 'card' | 'plain' = 'card'` (reflected) — mirrors `lr-card`'s/`<lr-agent-run>`'s
+  `appearance` vocabulary. `'card'` (the default) keeps the bordered, filled box. `'plain'` removes
+  the border, background, and corner radius, so a card nested inside a host frame that already draws
+  a border (e.g. `<lr-tool-result-view>`'s own chrome) doesn't double it. `plain` wins over `compact`
+  when both are set (nothing left to tighten).
+
+**Events:** none.
+
+**Slots:** default (the card body — typically one or more `lr-result-field` rows, though any
+content is accepted), `actions` (small header controls, e.g. a copy button, rendered alongside the
+title).
+
+**CSS parts:** `base` (outer bordered container), `header` (present in the DOM at all times so a
+later `slotchange` on `actions` is still observed, but `hidden` whenever there's no `title` and no
+`actions` content), `title` (truncates with an ellipsis when it overflows; carries its own native
+`title` attribute — the full string — so hovering the truncated text reveals it via the browser's
+default tooltip, scoped to just this element rather than the whole card), `actions` (`hidden`
+whenever the slot has no assigned content), `body`.
+
+**Themeable custom properties:** `--lr-result-card-compact-header-padding` (default
+`var(--lr-space-xs)`) — `[part="header"]` block/inline padding while `compact`;
+`--lr-result-card-compact-body-padding` (default `var(--lr-space-xs)`) — `[part="body"]` padding
+while `compact`; plus shared tokens — `--lr-space-xs`/`-s`, `--lr-color-border`/`-surface`/`-text`,
+`--lr-radius`.
+
+### `lr-result-field`
+
+A single label/value row — e.g. "Status: 200 OK" or "Duration: 340ms" — rendered as a dense
+"label: value" line by default, matching the compact, small-card presentation this pair exists for.
+
+**Properties:**
+- `label: string = ''` — the field name, e.g. "Status". Leave unset to render a value with no label.
+- `value: string = ''` — plain-text value, e.g. "200 OK". Ignored once the default slot carries real
+  content.
+
+**Events:** none.
+
+**Slots:** default — rich value content (e.g. a `lr-chip` status badge, or a plain text override),
+taking precedence over `value` whenever it has any assigned content. "Real content" means any
+assigned *element* (even one with no text of its own, like an attribute-driven status badge) or any
+non-whitespace text node — both a rich slotted badge and a plain-text override are caught.
+
+**CSS parts:** `base` (row container), `label` (including its trailing colon), `value` (wrapper
+around either the slotted content or the plain `value` text).
+
+**Themeable custom properties:** shared tokens only — `--lr-space-xs`, `--lr-color-text`/
+`-text-quiet`, `--lr-font`.
+
+**Optional peer deps:** none (either component).
+
+```html
+<lr-result-card title="Weather">
+  <lr-result-field label="Status" value="200 OK"></lr-result-field>
+  <lr-result-field label="Duration" value="340ms"></lr-result-field>
+  <lr-result-field label="Provider">
+    <lr-chip tone="success">OpenWeather</lr-chip>
+  </lr-result-field>
+</lr-result-card>
+```
+
+**Known gotchas:**
+- `HTMLElement.textContent` read on a shadow-DOM wrapper containing a `<slot>` does NOT include the
+  slot's assigned/projected light-DOM content — only literal fallback children of the `<slot>` tag
+  itself (there are none here). Asserting against `[part="value"]`'s own `.textContent` to check
+  rendered slotted content will read as empty even when the component is rendering correctly;
+  assert against the slot's `assignedNodes()`/`assignedElements()` instead.
+
+---

package/llms/components/lr-result-field.md

@@ -0,0 +1,100 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/agent-tools.md — do not edit this file. -->
+
+# `lr-result-field`
+
+- **Import** `import '@aceshooting/lyra-ui/components/agent-tools/result-card/result-field.js';` (registers the tag; side-effect import)
+- **Class** `LyraResultField`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/result-card/result-field.class.js`
+- **Family** `components/agent-tools/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Documented with** `lr-result-card` (same section below)
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-result-card` / `lr-result-field`
+
+A small, tightly-coupled pair giving any custom `lr-tool-result-view` renderer (registered via
+`registerToolRenderer()` in `../tool-result-view/registry.js`) a consistent "small bordered card +
+label/value row" visual language, without each one hand-rolling its own box. Neither component has
+any code dependency on the tool-result-view registry itself — they're generically usable anywhere a
+small card/field shell is useful.
+
+### `lr-result-card`
+
+A small bordered card shell. Purely visual, with no state of its own beyond slot-presence tracking.
+
+**Properties:**
+- `title: string = ''` — small heading for the card. Leave unset for an untitled card (e.g. a bare
+  block of `lr-result-field` rows with no natural heading).
+- `compact: boolean = false` (reflected) — tighter header/body padding for dense contexts (a card
+  rendered as a row in a transcript or result list), same convention as `<lr-agent-run>`'s own
+  `compact`. Purely a density knob: the border and background stay, so use `appearance="plain"`
+  instead to drop the chrome entirely.
+- `appearance: 'card' | 'plain' = 'card'` (reflected) — mirrors `lr-card`'s/`<lr-agent-run>`'s
+  `appearance` vocabulary. `'card'` (the default) keeps the bordered, filled box. `'plain'` removes
+  the border, background, and corner radius, so a card nested inside a host frame that already draws
+  a border (e.g. `<lr-tool-result-view>`'s own chrome) doesn't double it. `plain` wins over `compact`
+  when both are set (nothing left to tighten).
+
+**Events:** none.
+
+**Slots:** default (the card body — typically one or more `lr-result-field` rows, though any
+content is accepted), `actions` (small header controls, e.g. a copy button, rendered alongside the
+title).
+
+**CSS parts:** `base` (outer bordered container), `header` (present in the DOM at all times so a
+later `slotchange` on `actions` is still observed, but `hidden` whenever there's no `title` and no
+`actions` content), `title` (truncates with an ellipsis when it overflows; carries its own native
+`title` attribute — the full string — so hovering the truncated text reveals it via the browser's
+default tooltip, scoped to just this element rather than the whole card), `actions` (`hidden`
+whenever the slot has no assigned content), `body`.
+
+**Themeable custom properties:** `--lr-result-card-compact-header-padding` (default
+`var(--lr-space-xs)`) — `[part="header"]` block/inline padding while `compact`;
+`--lr-result-card-compact-body-padding` (default `var(--lr-space-xs)`) — `[part="body"]` padding
+while `compact`; plus shared tokens — `--lr-space-xs`/`-s`, `--lr-color-border`/`-surface`/`-text`,
+`--lr-radius`.
+
+### `lr-result-field`
+
+A single label/value row — e.g. "Status: 200 OK" or "Duration: 340ms" — rendered as a dense
+"label: value" line by default, matching the compact, small-card presentation this pair exists for.
+
+**Properties:**
+- `label: string = ''` — the field name, e.g. "Status". Leave unset to render a value with no label.
+- `value: string = ''` — plain-text value, e.g. "200 OK". Ignored once the default slot carries real
+  content.
+
+**Events:** none.
+
+**Slots:** default — rich value content (e.g. a `lr-chip` status badge, or a plain text override),
+taking precedence over `value` whenever it has any assigned content. "Real content" means any
+assigned *element* (even one with no text of its own, like an attribute-driven status badge) or any
+non-whitespace text node — both a rich slotted badge and a plain-text override are caught.
+
+**CSS parts:** `base` (row container), `label` (including its trailing colon), `value` (wrapper
+around either the slotted content or the plain `value` text).
+
+**Themeable custom properties:** shared tokens only — `--lr-space-xs`, `--lr-color-text`/
+`-text-quiet`, `--lr-font`.
+
+**Optional peer deps:** none (either component).
+
+```html
+<lr-result-card title="Weather">
+  <lr-result-field label="Status" value="200 OK"></lr-result-field>
+  <lr-result-field label="Duration" value="340ms"></lr-result-field>
+  <lr-result-field label="Provider">
+    <lr-chip tone="success">OpenWeather</lr-chip>
+  </lr-result-field>
+</lr-result-card>
+```
+
+**Known gotchas:**
+- `HTMLElement.textContent` read on a shadow-DOM wrapper containing a `<slot>` does NOT include the
+  slot's assigned/projected light-DOM content — only literal fallback children of the `<slot>` tag
+  itself (there are none here). Asserting against `[part="value"]`'s own `.textContent` to check
+  rendered slotted content will read as empty even when the component is rendering correctly;
+  assert against the slot's `assignedNodes()`/`assignedElements()` instead.
+
+---

package/llms/components/lr-retrieval-results.md

@@ -0,0 +1,111 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/retrieval.md — do not edit this file. -->
+
+# `lr-retrieval-results`
+
+- **Import** `import '@aceshooting/lyra-ui/components/retrieval/retrieval-results/retrieval-results.js';` (registers the tag; side-effect import)
+- **Class** `LyraRetrievalResults`, also available unregistered from `@aceshooting/lyra-ui/components/retrieval/retrieval-results/retrieval-results.class.js`
+- **Family** `components/retrieval/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-retrieval-results`
+
+Orchestration-level ranked-chunk surface: takes raw `RetrievalChunk[]` and adds deduplication,
+optional source grouping, multi-selection, pagination/infinite loading, and a compact/expanded
+switch. Each row wraps exactly one chunk in an internal `lr-chunk-inspector` (fed a single-element
+array), reusing its score bar, tier coloring, title+page rendering, and expandable text verbatim.
+Large sets window through an internal `lr-virtual-list`.
+
+**Properties:**
+- `chunks: RetrievalChunk[] = []` (attribute: false) — **`RetrievalChunk`, imported from
+  `@aceshooting/lyra-ui/ai`** (`src/ai/types.ts`): `{ id: string; text: string; score: number;
+  source: DocumentRef; metadata?: Record<string, unknown> }`. The raw, un-deduplicated/unsorted/
+  ungrouped result set; host-owned. Internally mapped to `lr-chunk-inspector`'s flatter `LyraChunk`
+  via `source.id → sourceId`, `source.name → title` (no `page`/`anchor` — `RetrievalChunk` carries
+  neither, and they're left unset rather than guessed from `metadata`)
+- `selectedIds: string[] = []` (attribute: false) — controlled selection by chunk `id`. The component
+  updates its own copy on toggle *then* emits `lr-select`; reassign to control. An id with no
+  matching chunk is harmless
+- `selectable: boolean = true` (reflected) — shows a per-row `lr-checkbox`
+- `dedupe: boolean = true` (reflected) — drops duplicate `id`s, keeping the higher `score`
+- `sort: 'score' | 'none' = 'score'` — `'score'` sorts descending; `'none'` preserves given order
+- `grouping: 'source' | 'none' = 'none'` — `'source'` buckets rows under a header per `source.id`,
+  each bucket ordered by its own best-scoring chunk, and **always** virtualizes regardless of
+  `virtualizeAt`
+- `presentation: 'compact' | 'expanded' = 'expanded'` — `'expanded'` shows each chunk's full row
+  (score bar, text preview with its own toggle) plus any `metadata`; `'compact'` shows title + score
+  bar only and omits `metadata` entirely
+- `thresholds: { high: number; medium: number } = { high: 0.75, medium: 0.5 }` (attribute: false) —
+  forwarded to every per-row `lr-chunk-inspector`
+- `virtualizeAt: number = 50` (attribute `virtualize-at`) — row count (after dedup, before grouping)
+  above which rendering switches to the internal `lr-virtual-list`
+- `activeId: string = ''` (attribute `active-id`) — the chunk currently open in a viewer; forwarded
+  to each row and to the virtual list (which scrolls the matching row into view)
+- `loading: boolean = false` (reflected)
+- `hasMore: boolean = false` (attribute `has-more`, reflected) — while virtualized, forwarded to the
+  virtual list so scroll-near-bottom fires `lr-load-more`; otherwise shows the built-in footer button
+- `error: string = ''` — non-empty replaces the whole result view with a `role="alert"` message.
+  Caller-supplied text, not localized (app/network data, not library copy)
+- `label: string = ''` — accessible name; defaults to the localized `chunkInspectorLabel`
+
+**Events:**
+- `lr-select` (`detail: RetrievalResultsSelectDetail` = `{ ids: string[]; chunks: RetrievalChunk[] }`)
+  — the *complete* updated selection, both as ids and as the matching deduplicated records, so a host
+  needn't re-look-up ids against its own copy on every toggle.
+- `lr-load-more` (`detail: undefined`) — from the virtual list's scroll-near-bottom detection while
+  virtualized, or the `[part="load-more"]` button otherwise. Only fires while `hasMore` is true and
+  `loading` is false.
+- `lr-chunk-open` (`detail: { id: string; sourceId: string }`) — forwarded verbatim from a row's
+  `lr-chunk-inspector`; the event a host routes into `lr-document-viewer`.
+
+**Slots:** none.
+
+**CSS parts:** `base`, `error` (`role="alert"`, while `error` is non-empty), `spinner` (initial-load
+`lr-spinner`, while `loading` and `chunks` is still empty), `empty` (when `chunks` is empty and
+neither `error` nor `loading` is set), `row` (a plain element in this shadow root below the
+virtualization threshold; exported from the internal `lr-virtual-list`'s own `row` part while
+virtualized — `::part(row)` reaches it either way), `group-header` (exported from the virtual list's
+`group` part; grouped/virtualized mode only), `select` (per-row `lr-checkbox`, omitted when
+`selectable` is false), `row-body` (carries `data-selected`), `row-body-selected` (additional part
+on a selected `row-body`), `metadata` (a `<dl>`; omitted when the chunk has none or while
+`presentation="compact"`), `metadata-entry`, `metadata-term` (the `<dt>` carrying a metadata key),
+`metadata-value` (the `<dd>` carrying its value), `load-more-row`, `load-more`.
+
+The per-row `lr-chunk-inspector`'s own parts are forwarded onward under a `chunk-` prefix —
+`chunk`, `chunk-current`, `chunk-score`, `chunk-score-current`, `chunk-score-bar`,
+`chunk-score-fill`, `chunk-score-fill-success`, `chunk-score-fill-warning`,
+`chunk-score-fill-danger`, `chunk-open-button`,
+`chunk-title`, `chunk-text`, `chunk-text-clamped`, `chunk-toggle`. Those elements sit two shadow
+hops deep while virtualized, so this forwarding is the only way to reach them.
+
+Selection state is exposed as the additional `row-body-selected` part name rather than through the
+`data-selected` attribute, because Shadow Parts forbids an attribute selector after `::part()`:
+`::part(row-body)[data-selected]` is invalid CSS, and while virtualized `::part()` is the only way
+in. `data-selected` is unchanged. A state part is a second token in the same `part` attribute, so
+a `[part~="…"]` (not `[part="…"]`) selector is the one that matches inside a tree. The `<dt>`/`<dd>`
+carry their own part names for the same class of reason — `::part()` matches a single element and
+cannot be followed by a descendant combinator, so `::part(metadata-entry) dt` reaches nothing.
+
+**Themeable custom properties:** `--lr-retrieval-results-selected-border` (default
+`var(--lr-color-brand)`) — the inline-start border color marking a selected row body
+(`::part(row-body-selected)`). A
+border rather than a fill by design: the row's own text (the nested chunk inspector's quiet-toned
+score line in particular) is sized and colored for the page's default surface, and a tinted
+background can drop it below the required contrast ratio, while a border-only indicator carries no
+such risk — so recoloring this hook is contrast-safe. 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(row-body)[data-selected]` is invalid CSS — Shadow Parts forbids an attribute selector after
+`::part()` — which previously left re-pointing the library-wide `--lr-color-brand` token as the only
+lever, repainting every other brand surface with it. Plus shared tokens otherwise.
+
+**Optional peer deps:** none.
+
+**Known gotchas:**
+- While virtualized, each row's content lives inside `lr-virtual-list`'s shadow root, not this
+  component's.
+- Below the virtualization threshold, scroll-near-bottom isn't a meaningful gesture, so a
+  `[part="load-more"]` button takes its place (replaced by a spinner while `loading`).
+
+---

package/llms/components/lr-retrieval-search.md

@@ -0,0 +1,70 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/retrieval.md — do not edit this file. -->
+
+# `lr-retrieval-search`
+
+- **Import** `import '@aceshooting/lyra-ui/components/retrieval/retrieval-search/retrieval-search.js';` (registers the tag; side-effect import)
+- **Class** `LyraRetrievalSearch`, also available unregistered from `@aceshooting/lyra-ui/components/retrieval/retrieval-search/retrieval-search.class.js`
+- **Family** `components/retrieval/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-retrieval-search`
+
+Query bar for a retrieval/RAG surface: query text, an active filter/scope chip row, a
+vector/keyword/hybrid mode selector, and loading/error/empty feedback. Emits `RetrievalQuery` on
+submit. Fully controlled; performs no retrieval itself. Composes `lr-input type="search"`,
+`lr-segmented`, `lr-chip`/`lr-chip-group`, `lr-spinner`, and a compact `lr-empty`.
+
+**Properties:**
+- `query: string = ''` — the query text. The internal `lr-input` updates it optimistically as the
+  user types; a host reassignment always wins
+- `mode: LyraRetrievalMode = 'hybrid'` — `LyraRetrievalMode = RetrievalQuery['mode'] = 'vector' |
+  'keyword' | 'hybrid'`, re-exported here rather than redefined
+- `filters: Record<string, unknown> = {}` (attribute: false) — arbitrary metadata filters, rendered
+  as removable `"{key}: {value}"` chips. Controlled
+- `scope: string[] = []` (attribute: false) — source-scope ids/labels this query is restricted to,
+  rendered as removable chips alongside `filters`. Controlled
+- `loading: boolean = false` (reflected) — host-driven busy flag; this component cannot know when a
+  request resolves
+- `errorText: string = ''` (attribute `error-text`) — last failed search's message, shown verbatim
+  (caller-owned text, not localized) in a `role="alert"` region
+- `empty: boolean = false` (reflected) — host-driven "the last completed search returned zero
+  results"; never inferred, since this component holds no results data (see `lr-retrieval-results`)
+- `placeholder: string = ''` — falls back to the localized generic "Search" placeholder, which also
+  becomes the field's accessible name
+- `label: string = ''` — accessible name for the `role="search"` landmark; falls back to a localized
+  default
+- `accessibleLabel: string | null = null` (attribute `aria-label`) — overrides the landmark's
+  computed accessible name; wins over `label` and the localized default, and attribute-reflects from
+  a host-level `aria-label`
+
+**Events:**
+- `lr-search` (`detail: RetrievalQuery` from `@aceshooting/lyra-ui/ai` = `{ text: string;
+  filters?: Record<string, unknown>; mode: 'vector' | 'keyword' | 'hybrid'; scope?: string[] }`) —
+  Enter in the query field, or the submit button while not `loading`.
+- `lr-cancel` (`detail: CancelEventDetail` from `@aceshooting/lyra-ui/ai` = `{ reason?: string }`) —
+  either the button was clicked while `loading` (`detail: {}`), or a new submission superseded an
+  in-flight one (`detail: { reason: 'superseded' }`, fired immediately *before* the new `lr-search`).
+- `lr-filters-change` (`detail: RetrievalFiltersChangeDetail` = `{ filters: Record<string, unknown>;
+  scope: string[] }`) — a chip's remove button was activated; the complete already-updated next
+  state, not a delta. The component updates its own copy first, then emits; reassign to control.
+
+**Slots:** none.
+
+**CSS parts:** `base` (the `role="search"` landmark), `row`, `query`, `mode`, `submit` (reads
+"Search" while idle, "Cancel" while `loading`), `filters` (omitted entirely when both `filters` and
+`scope` are empty), `spinner` (only while `loading`), `error` (`role="alert"`, only when `errorText`
+is non-empty and not `loading`), `empty` (only when `empty` and neither `loading` nor `errorText`).
+
+**Themeable custom properties:** shared tokens only.
+
+**Optional peer deps:** none.
+
+**Known gotchas:**
+- Submitting while `loading` is already true **supersedes** the in-flight request: `lr-cancel` fires
+  immediately before the new `lr-search`. Clicking the submit button (rather than pressing Enter)
+  while `loading` only emits `lr-cancel` and does not resubmit.
+
+---

package/llms/components/lr-retrieval-trace.md

@@ -0,0 +1,66 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/retrieval.md — do not edit this file. -->
+
+# `lr-retrieval-trace`
+
+- **Import** `import '@aceshooting/lyra-ui/components/retrieval/retrieval-trace/retrieval-trace.js';` (registers the tag; side-effect import)
+- **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
+- **Optional peers** none
+- **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'`
+- `RetrievalStageEvidence { text?: string; chunks?: RetrievalChunk[]; metadata?: Record<string,
+  unknown> }` — `chunks` is **`RetrievalChunk` from `@aceshooting/lyra-ui/ai`** verbatim, rendered
+  through `lr-chunk-inspector` (`source.id → sourceId`, `source.name → title`); `text` is free-form
+  (e.g. the rewritten query, an embedding model id); `metadata` renders as a plain key/value list. 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; falls back to a host `aria-label`, then
+  the waterfall's own localized default
+
+**Events:** `lr-stage-select` (`detail: { id: string }`, a stage's bar was activated — click, Enter,
+Space), `lr-stage-toggle` (`detail: { id: 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).
+
+**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 `<dl>`), `evidence-metadata-row` (one key/value pair), `evidence-metadata-key`
+(`<dt>`), `evidence-metadata-value` (`<dd>`).
+
+**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.

package/llms/components/lr-rubric-form.md

@@ -0,0 +1,42 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/forms.md — do not edit this file. -->
+
+# `lr-rubric-form`
+
+- **Import** `import '@aceshooting/lyra-ui/components/forms/rubric-form/rubric-form.js';` (registers the tag; side-effect import)
+- **Class** `LyraRubricForm`, also available unregistered from `@aceshooting/lyra-ui/components/forms/rubric-form/rubric-form.class.js`
+- **Family** `components/forms/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-rubric-form`
+
+A configurable annotation rubric (LangSmith annotation-queue style): score, category, and
+freeform-comment keys with a submit-and-next flow for working through an eval queue. Each
+`RubricKey.type` routes to an existing sibling control: `score` renders `<lr-segmented>` or
+`<lr-slider>`; `category` renders `<lr-select>` or `<lr-checkbox-group>` (`multiple`); `comment`
+renders `<lr-textarea>`.
+
+**Properties:** `keys: RubricKey[] = []` (attribute: false, each `{ key, type, label?, description?,
+required?, min?, max?, step? }`), `value: RubricValue = {}` (attribute: false), `itemId: string = ''`
+(attribute `item-id`, reflected), `hasNext: boolean = false` (attribute `has-next`), `skippable:
+boolean = false`, and the shared form properties `name` and `disabled`. `errors: Record<string,
+string>` is the current per-key validation-message state.
+
+**Slots:** `actions` — extra host controls rendered in the footer beside Submit/Skip.
+
+**Events:** `lr-input` (`detail: { value }`), `lr-validity-change` (`detail: { valid, errors }`,
+fired only on an actual change), `lr-submit` (`detail: { value, itemId }`), and `lr-skip`
+(`detail: { itemId }`, `skippable` only).
+
+**CSS parts:** `base` (the outer wrapper), `field` (one key's wrapper), `label`, `description`,
+`scale` (the rendered score/category/comment control's wrapper), `error` (a field-level validation
+message), `footer`, `submit`, `skip` (only rendered when `skippable`), `empty` (shown when `keys` has
+no entries), and `unsupported` (the fallback note for a key whose `type` is outside the three
+supported ones).
+
+**Themeable custom properties:** shared tokens only. The footer's disabled `submit`/`skip` buttons
+dim through `--lr-opacity-disabled`, the same library-wide token every other disabled control
+reads — so retuning `--lr-theme-opacity-disabled` keeps this form's disabled state consistent with
+the rest of the UI instead of needing a `::part()` rule here.

package/llms/components/lr-scatter-chart.md

@@ -0,0 +1,72 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/charts.md — do not edit this file. -->
+
+# `lr-scatter-chart`
+
+- **Import** `import '@aceshooting/lyra-ui/components/charts/chart/scatter-chart.js';` (registers the tag; side-effect import)
+- **Class** `LyraScatterChart`, also available unregistered from `@aceshooting/lyra-ui/components/charts/chart/scatter-chart.class.js`
+- **Family** `components/charts/` — see `llms/index.md` for its siblings
+- **Optional peers** `chart.js`, `chartjs-plugin-zoom` — see `llms/peers.md`
+- **Documented with** `lr-line-chart`, `lr-bar-chart`, `lr-pie-chart`, `lr-doughnut-chart`, `lr-radar-chart`, `lr-polar-area-chart`, `lr-bubble-chart` (same section below)
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## Typed subclasses: `lr-line-chart`, `lr-bar-chart`, `lr-pie-chart`, `lr-doughnut-chart`, `lr-radar-chart`, `lr-polar-area-chart`, `lr-bubble-chart`, `lr-scatter-chart`
+
+Each is `LyraChart` with `type` locked to a fixed value — respectively `line`, `bar`, `pie`,
+`doughnut`, `radar`, `polarArea`, `bubble`, `scatter` — via a real `get`/`set` accessor pair the
+shared `lockChartType()` helper installs on the subclass's own prototype (`declare type: '…'`
+narrows the TS type at compile time; the runtime lock is the `Object.defineProperty` pair alongside
+it — the same helper `lr-histogram` uses), not merely a class-field default a later assignment
+could still override.
+
+Everything else is inherited verbatim from `lr-chart`; each name below has the same type, default,
+and behavior there. **See `llms/components/lr-chart.md` for the details, code example, and gotchas
+of every entry in these lists.**
+
+**Properties:** `labels`, `datasets`, `legend`, `legendPosition` (attribute `legend-position`),
+`valueFormatter`, `area`, `zoom`, `height`, `xLabel` (`x-label`), `yLabel` (`y-label`), `y2Label`
+(`y2-label`), `beginAtZero` (`begin-at-zero`), `horizontal`, `stacked`, `config`, `accessibleLabel`
+(`accessible-label`), `accessibleDescription` (`accessible-description`), `showDataTable`
+(`show-data-table`), `chartArea` (readonly). `type` is the only member that differs: read-only,
+locked to this tag's value.
+
+**Methods:** `resetZoom()`, `refreshTheme()`.
+
+**Events:** `lr-zoom` (`detail: { zoomed: boolean }`), `lr-point-click` (`detail: { datasetIndex,
+index, label, value }`).
+
+**Slots:** `data-table`, `center`.
+
+**CSS parts:** `base`, `canvas`, `reset-zoom-button`, `description`, `data-table`, `center`,
+`error` (`role="alert"` message rendered in place of `canvas` when the optional `chart.js` peer
+dependency fails to load — see `llms/components/lr-chart.md`).
+
+**Themeable custom properties:** `--lr-chart-height`, `--lr-chart-grid-color`,
+`--lr-chart-tick-color`, `--lr-chart-legend-color`, `--lr-chart-tooltip-bg`,
+`--lr-chart-tooltip-text`.
+
+**Optional peer deps:** same as `lr-chart` — `chart.js`, plus `chartjs-plugin-zoom` only once
+`zoom` is set.
+
+```html
+<lr-bar-chart legend></lr-bar-chart>
+<lr-pie-chart></lr-pie-chart>
+<script>
+  document.querySelector('lr-bar-chart').labels = ['A', 'B'];
+  document.querySelector('lr-bar-chart').datasets = [{ label: 'Count', data: [4, 9] }];
+
+  document.querySelector('lr-pie-chart').labels = ['A', 'B', 'C'];
+  document.querySelector('lr-pie-chart').datasets = [{ label: 'Share', data: [30, 45, 25], color: ['#2563eb', '#16a34a', '#dc2626'] }];
+</script>
+```
+
+**Known gotchas (in addition to the core `lr-chart` list in `llms/components/lr-chart.md`):**
+- `type` truly is locked per subclass: `<lr-pie-chart type="bar">` or `el.type = 'bar'` at runtime
+  is a genuine no-op (the accessor's setter silently ignores the write), not a footgun like a plain
+  overridden class-field default would be.
+- `lr-bubble-chart` needs `Series.points` entries with an `x`/`y`/`r` triple, but `Series.points`
+  is typed as `{x, y, label?}[]` with no `r` field — cast the array through `as unknown as
+  Series['points']` (or a local `BubblePoint` type) when constructing bubble data.
+
+---

package/llms/components/lr-scroller.md

@@ -0,0 +1,47 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/layout.md — do not edit this file. -->
+
+# `lr-scroller`
+
+- **Import** `import '@aceshooting/lyra-ui/components/layout/scroller/scroller.js';` (registers the tag; side-effect import)
+- **Class** `LyraScroller`, also available unregistered from `@aceshooting/lyra-ui/components/layout/scroller/scroller.class.js`
+- **Family** `components/layout/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-scroller`
+
+Responsive overflow surface with optional previous/next controls. The default slot remains the
+consumer's content, and the viewport is a native scroll container that works in narrow panels as
+well as full-width layouts.
+
+**Properties:**
+- `orientation: 'horizontal' | 'vertical' = 'horizontal'` (reflected)
+- `controls: boolean = false` (reflected) — show previous/next controls
+- `hideScrollbar: boolean = false` (attribute `hide-scrollbar`, reflected)
+- `scrollStep: number = 0` (attribute `scroll-step`) — custom step; zero uses 80% of the viewport
+- `label: string = ''` — accessible region name; a host `aria-label` is used when set
+
+**Events:** `lr-scroll` with `scrollStart`, `scrollEnd`, `scrollLeft`, and `scrollTop` in the
+detail object.
+
+**Slots:** default scrollable content.
+
+**CSS parts:** `base`, `viewport`, `content`, `previous`, `next`, `control` (shared by `previous` and
+`next`), and `previous-glyph`/`next-glyph` (the chevron inside each, mirrored under RTL).
+
+**Themeable custom properties:** `--lr-scroller-control-size` (default `var(--lr-size-2rem)`) — the
+previous/next control's box size; the interactive target never shrinks below `--lr-icon-button-size`
+regardless. `--lr-scroller-min-block-size` (default `var(--lr-size-10rem)`) — the vertical
+orientation's minimum block size, ignored while horizontal.
+
+```html
+<lr-scroller controls label="Project cards">
+  <lr-card>Solar</lr-card>
+  <lr-card>Wind</lr-card>
+  <lr-card>Battery</lr-card>
+</lr-scroller>
+```
+
+---