@aceshooting/lyra-ui 5.0.0 → 5.1.0

package/llms/components/lr-responsive-panel.md

@@ -0,0 +1,112 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/layout.md — do not edit this file. -->
+
+# `lr-responsive-panel`
+
+- **Import** `import '@aceshooting/lyra-ui/components/layout/responsive-panel/responsive-panel.js';` (registers the tag; side-effect import)
+- **Class** `LyraResponsivePanel`, also available unregistered from `@aceshooting/lyra-ui/components/layout/responsive-panel/responsive-panel.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-responsive-panel`
+
+The same slotted content either docked inline in the page's normal layout flow (desktop) or
+presented as a full-screen/bottom-sheet overlay (mobile), depending on viewport width. First-party
+invention (no Web Awesome equivalent). Typical uses: a settings panel or a conversation-history
+sidebar that's a permanent docked pane on a wide screen but a modal on a phone.
+
+**Properties:**
+- `open: boolean = false` (reflected) — in the inline presentation this just means visible/mounted;
+  in the overlay presentation this is the actual modal open/closed state.
+- `mode: ResponsivePanelMode = 'auto'` (reflected) — `'auto'` tracks `mobile-breakpoint` live;
+  `'inline'`/`'overlay'` force that presentation regardless of viewport width.
+- `variant: ResponsivePanelVariant = 'fullscreen'` (reflected) — only affects the overlay
+  presentation's visual treatment: `'fullscreen'` covers the whole viewport; `'bottom-sheet'` slides
+  up from the bottom and doesn't cover the full height. Has no visual effect while the effective
+  presentation resolves to `'inline'`.
+- `label: string = ''` — accessible name for the overlay presentation's `role="dialog"`, used
+  verbatim when set. When empty, falls back to the `header` slot's content: a heading element
+  (`h1`–`h6` or `[role="heading"]`) among the slotted header content wins if present, otherwise the
+  header slot's combined text content is used (mirrors `lr-dialog`'s `detectHeading()` fallback,
+  via `aria-label` rather than `aria-labelledby` since the header content is light DOM while
+  `[part="panel"]` is in shadow DOM). A panel opened with neither `label` nor header content still
+  renders `role="dialog"` with no accessible name. Unused in the inline presentation, which has no
+  dialog semantics to name.
+- `mobileBreakpoint: string = '768px'` (attribute `mobile-breakpoint`) — CSS length passed to
+  `matchMedia` as `(max-width: <this>)` to decide, in `mode="auto"`, whether the effective
+  presentation is `'overlay'` (below/at this width) or `'inline'` (above it).
+
+**Methods:** `close(reason: ResponsivePanelCloseReason = 'api'): void` — closes the panel (sets
+`open = false`), emits `lr-close` with `reason`, and — only in the overlay presentation — returns
+focus to whichever element triggered the open. No-op if already closed. Built-in overlay triggers
+call this with `'escape'`/`'backdrop'`; a consumer's own close affordance (a footer button, a docked
+panel's own toggle) should call it directly with its own reason string.
+
+**Events:** `lr-close` (`detail: ResponsivePanelCloseReason` = `'escape'|'backdrop'|'api'|string`;
+fired by the overlay presentation's built-in dismiss triggers — Escape, backdrop click — and by any
+`close()` call, in either presentation; a plain `open = false` property write does **not** fire it,
+only going through `close()` counts as a dismissal), `lr-mode-change`
+(`detail: ResponsivePanelModeChangeDetail` = `{ mode: ResponsivePanelEffectiveMode }`; fired whenever
+the *effective* mode — not the `mode` prop's possibly-`'auto'` literal value — changes between
+`'inline'` and `'overlay'`; never fired on the initial render, only for a live change thereafter).
+
+**Slots:** default (the panel body), `header` (optional header content, rendered above the body),
+`footer` (optional footer content, e.g. action buttons, rendered below the body).
+
+**CSS parts:** `base`, `backdrop`, `panel`, `header`, `body`, `footer` (`backdrop` is only rendered
+in the overlay presentation).
+
+**Themeable custom properties:** `--lr-responsive-panel-overlay-color` (default
+`var(--lr-color-overlay)` — the overlay presentation's backdrop scrim color), plus shared tokens (`--lr-color-border`, `--lr-color-surface`,
+`--lr-space-*`, `--lr-radius`, `--lr-shadow`).
+
+**Optional peer deps:** none.
+
+```html
+<lr-responsive-panel id="settings-panel" label="Settings" variant="bottom-sheet" mobile-breakpoint="768px">
+  <span slot="header"><h2>Settings</h2></span>
+  <div>Panel body content — a form, a list, anything.</div>
+  <span slot="footer"><button onclick="document.getElementById('settings-panel').close()">Done</button></span>
+</lr-responsive-panel>
+```
+
+Breakpoint detection uses `matchMedia('(max-width: ' + mobileBreakpoint + ')')`, re-evaluated live
+while connected — resizing/rotating a device that crosses the breakpoint while `mode="auto"` (the
+default) updates the effective presentation without unmounting or re-creating the slotted content.
+Inline and overlay presentations share the same shadow DOM, so slotted content and scroll position
+survive the transition. Focus already inside the panel is preserved. If focus is outside when an
+open inline panel becomes an overlay, focus moves to the first composed focus target (falling back
+to the panel), so it cannot remain behind `aria-modal="true"`. Closing restores the element captured
+when the panel originally opened, even when that original open happened inline. The overlay
+presentation participates in the shared modal stack rather than nesting a `<lr-dialog>`.
+
+The package root also exports the pure `resolveEffectiveMode(mode: ResponsivePanelMode,
+belowBreakpoint: boolean): ResponsivePanelEffectiveMode` resolver — renamed on export to
+`resolveResponsivePanelEffectiveMode` to avoid a name collision — alongside the
+`ResponsivePanelMode`/`ResponsivePanelEffectiveMode`/`ResponsivePanelVariant`/
+`ResponsivePanelCloseReason`/`ResponsivePanelModeChangeDetail` types. It's the same logic the
+element's internal `matchMedia` listener calls: `'inline'`/`'overlay'` pass straight through
+unchanged; `'auto'` resolves to `'overlay'` when `belowBreakpoint` is true, `'inline'` otherwise —
+exposed standalone so a consumer can compute or unit-test the same resolution without a real browser
+window.
+
+**Known gotchas:**
+- assigning `open` directly still does not emit `lr-close`; use `close()` when the dismissal
+  event/reason is required. While overlay chrome is active, however, the `true` → `false` state
+  transition restores opener focus regardless of whether it came from `close()`, a property write,
+  or attribute removal.
+- crossing inline → overlay while already open preserves focus that is already inside and moves
+  outside focus into the panel; do not expect focus to remain on page content behind the modal.
+- `variant="bottom-sheet"` has no visible effect at all while the effective presentation is
+  `'inline'` — it only changes the overlay presentation's anchoring/height.
+- a reconnect that preserves the same element instance (e.g. a drag-and-drop reparent) resumes its
+  shared overlay registration and re-acquires the scroll lock if overlay chrome was still active
+  across the move — `disconnectedCallback`/`connectedCallback` fire back-to-back with no update in
+  between, so `willUpdate()` alone wouldn't otherwise notice.
+- the exported pure function is named `resolveEffectiveMode` in the component module but re-exported
+  from the package root as `resolveResponsivePanelEffectiveMode` — importing the un-prefixed name
+  from `@aceshooting/lyra-ui` will fail.
+
+---

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

@@ -0,0 +1,88 @@
+<!-- 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).
+
+**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:** shared tokens only — `--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,88 @@
+<!-- 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).
+
+**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:** shared tokens only — `--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,84 @@
+<!-- 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`), `metadata` (a `<dl>`; omitted when the
+chunk has none or while `presentation="compact"`), `metadata-entry`, `load-more-row`, `load-more`.
+
+**Themeable custom properties:** shared tokens only.
+
+**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,59 @@
+<!-- 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:** shared tokens only.
+
+**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,37 @@
+<!-- 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).

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

@@ -0,0 +1,70 @@
+<!-- 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`.
+
+**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.
+
+---