@aceshooting/lyra-ui 6.1.0 → 7.0.0

package/llms/components/lr-chip.md

@@ -6,6 +6,7 @@
 - **Class** `LyraChip`, also available unregistered from `@aceshooting/lyra-ui/components/overlays/chip/chip.class.js`
 - **Family** `components/overlays/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 5 parts, 13 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Documented with** `lr-chip-group` (same section below)
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
@@ -29,16 +30,13 @@ already follow.
   whole pill using a loud-color-on-quiet-tint convention; `neutral` has no dedicated token pair, so
   it falls back to a plain bordered-surface look)
 - `removable: boolean = false` (reflected — shows the remove (×) button)
-- `selected: boolean = false` (reflected) — opt-in toggle/pressed mode: when set, `[part='base']`
-  itself becomes focusable and keyboard-activatable (Enter/Space, mirroring native `<button>`
-  behavior), reflects `aria-pressed` (explicitly `"false"`, not omitted, whenever toggle mode is
-  active but unpressed), and toggles on click/activation, emitting `lr-chip-select`.
-  Has no effect (no interactive semantics added to `[part='base']`) when combined with `removable`,
-  since the remove button already nests inside `[part='base']` — a focusable descendant of a
-  `role="button"` ancestor isn't allowed there, and this component's two real use cases (a
-  chart-series visibility toggle, a category filter chip) never need both at once. `false` (the
-  default, with `toggleable` also left at its default) reproduces the exact passive-label-pill
-  output.
+- `selected: boolean = false` (reflected) — current value for opt-in toggle/pressed mode. Once
+  toggle mode is active, a separate native `[part='toggle-button']` owns focus, Enter/Space/click
+  activation, and explicit `"true"`/`"false"` `aria-pressed`; `[part='base']` remains a container
+  and the default-slot label is inert. Activation proposes the opposite value through the
+  cancelable `lr-chip-select` event and mutates `selected` only when that event is not prevented.
+  Has no toggle effect when combined with `removable`, where the remove button is the sole control.
+  `false` (with `toggleable` also left at its default) reproduces the passive label-pill output.
 - `toggleable: boolean = false` (reflected) — explicit opt-in into `selected`'s toggle/pressed
   interactive mode, independent of `selected`'s own current value. Setting `selected` to `true` at
   any point opts in automatically and keeps `toggleable` `true` from then on (enough for a chip that
@@ -51,16 +49,21 @@ already follow.
 
 **Events:** `lr-remove` (`detail: { value }` — the remove (×) button was activated via click or
 Enter/Space while focused; only rendered/reachable while `removable`), `lr-chip-select`
-(`detail: { value, selected }` — fired on click, or Enter/Space while focused, when `selected` mode
-is active and `removable` is not set; the chip has already toggled its own `selected` state by the
-time this fires)
+(`detail: { value, selected }` — cancelable; fired from the native toggle button on click or
+Enter/Space with the proposed next state when toggle mode is active and `removable` is not set.
+Calling `preventDefault()` keeps the current `selected` state unchanged)
 
-**Slots:** default (the chip's label content), `icon` (optional leading icon or status dot; nothing
-reserved for it — no extra gap — when left empty)
+**Methods:** `focus(options?)`, `blur()`, and `click()` forward to the active internal control
+(toggle or remove button); a passive chip's `click()` retains ordinary host behavior.
+
+**Slots:** default (the chip's label content; inert in toggle mode, so move links/buttons outside a
+toggleable chip), `icon` (optional leading icon or status dot; nothing reserved for it — no extra
+gap — when left empty)
 
 **CSS parts:** `base` (the pill's root container), `icon` (wrapper around the `icon` slot; hidden
-entirely while empty), `label` (wrapper around the default slot), `remove-button` (the remove (×)
-affordance, only rendered while `removable`)
+entirely while empty), `label` (non-interactive wrapper around the default slot), `toggle-button`
+(the real native toggle control, rendered over the label in toggle mode), `remove-button` (the
+remove (×) affordance, only rendered while `removable`)
 
 **Themeable custom properties:** `--lr-chip-accent`, `--lr-chip-bg`, `--lr-chip-border`
 (component-local trio swapped per `tone` rather than repeating background/color/border per part per

package/llms/components/lr-chunk-inspector.md

@@ -6,6 +6,7 @@
 - **Class** `LyraChunkInspector`, also available unregistered from `@aceshooting/lyra-ui/components/retrieval/chunk-inspector/chunk-inspector.class.js`
 - **Family** `components/retrieval/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 16 parts, 2 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`
 
 ---

package/llms/components/lr-citation-badge.md

@@ -6,6 +6,7 @@
 - **Class** `LyraCitationBadge`, also available unregistered from `@aceshooting/lyra-ui/components/retrieval/citation-badge/citation-badge.class.js`
 - **Family** `components/retrieval/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 4 parts, 3 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`
 
 ---
@@ -56,6 +57,11 @@ directly — set instead by the `:host([status=...])` rules), plus shared tokens
 `--lr-color-surface`, `--lr-color-border`, `--lr-shadow`, `--lr-space-s`/`-m`,
 `--lr-transition-fast`, `--lr-focus-ring-*`.
 
+> Retheming a badge from outside `<lr-citation-badge>` (e.g. per-source or per-confidence colors)?
+> Set `--lr-theme-*` on the ancestor wrapper, not `--lr-*` directly — see `llms/shared.md`'s
+> "Theming and design tokens" section for why a `--lr-*` override on a wrapper only reaches that
+> wrapper's *direct* children, not a nested `<lr-*>` host's shadow DOM.
+
 **Optional peer deps:** none.
 
 ```html

package/llms/components/lr-claim-evidence.md

@@ -0,0 +1,37 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/retrieval.md — do not edit this file. -->
+
+# `lr-claim-evidence`
+
+- **Import** `import '@aceshooting/lyra-ui/components/retrieval/claim-evidence/claim-evidence.js';` (registers the tag; side-effect import)
+- **Class** `LyraClaimEvidence`, also available unregistered from `@aceshooting/lyra-ui/components/retrieval/claim-evidence/claim-evidence.class.js`
+- **Family** `components/retrieval/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Themeable via** 11 parts, 0 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-claim-evidence`
+
+Controlled claim-by-claim grounding audit relating `GroundedClaim[]` to complete `Citation[]`
+records. Dangling citation ids are ignored rather than rendered as invented evidence.
+
+**Properties:** `claims: GroundedClaim[] = []` and `citations: Citation[] = []` (attribute: false);
+`selectedClaimId: string = ''` (attribute `selected-claim-id`); `label: string = ''`.
+`GroundedClaim = { id, text, status, citationIds, answerRange?, confidence?, explanation? }`, with
+`status: 'supported' | 'partially-supported' | 'unsupported' | 'contradicted'`. Claim confidence
+is clamped to 0–1 for localized percent display. `Citation` is the shared AI citation record
+(`id`, source/chunk ids, label, locator/ranges, quote, metadata).
+
+**Events:** `lr-claim-select` (`{ claim }`), `lr-citation-select` (`{ citation }`).
+
+**CSS parts:** `base`, `list`, `claim`, `claim-selected`, `claim-trigger`, `status`, `claim-text`,
+`confidence`, `explanation`, `evidence`, `empty`.
+
+Selection is controlled: activation emits the complete claim but does not assign
+`selectedClaimId`. Evidence preserves `citations` order and silently skips dangling ids.
+**Slots:** none. **Optional peer deps:** none.
+
+```ts
+import '@aceshooting/lyra-ui/components/retrieval/claim-evidence/claim-evidence.js';
+```

package/llms/components/lr-code-block-core.md

@@ -6,6 +6,7 @@
 - **Class** `LyraCodeBlockCore`, also available unregistered from `@aceshooting/lyra-ui/components/conversation/code-block/code-block-core.class.js`
 - **Family** `components/conversation/` — see `llms/index.md` for its siblings
 - **Optional peers** `shiki` — see `llms/peers.md`
+- **Themeable via** 11 parts, 2 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`
 
 ---
@@ -72,9 +73,7 @@ Identical behavior to `<lr-code-block>`'s own method.
 highlighted HTML, and always fires regardless of whether the actual OS clipboard write succeeded),
 `lr-toggle` (`detail: { collapsed: boolean }` — fired when the built-in collapse/expand header
 button is activated), `lr-line-click` (`detail: { line: number }` — a gutter line number was
-activated while `interactiveLines` is set), `lr-highlight-activate` (`detail: { id: string }` —
-declared for parity with this library's other anchor-target viewers; not currently emitted by this
-component), `lr-text-select` (`detail: { text, anchor, rects }` — a text selection inside the code
+activated while `interactiveLines` is set), `lr-text-select` (`detail: { text, anchor, rects }` — a text selection inside the code
 body ended; `anchor` is a `line-range` anchor covering the selected lines).
 
 **Slots:** none.

package/llms/components/lr-code-block.md

@@ -6,6 +6,7 @@
 - **Class** `LyraCodeBlock`, also available unregistered from `@aceshooting/lyra-ui/components/conversation/code-block/code-block.class.js`
 - **Family** `components/conversation/` — see `llms/index.md` for its siblings
 - **Optional peers** `shiki` — see `llms/peers.md`
+- **Themeable via** 11 parts, 4 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`
 
 ---
@@ -74,8 +75,7 @@ highlighted HTML, and always fires regardless of whether the actual OS clipboard
 `lr-toggle` (`detail: { collapsed: boolean }` — fired when the built-in collapse/expand header
 button is activated, same event name/shape convention as `<lr-thinking-panel>`'s own `lr-toggle`),
 `lr-line-click` (`detail: { line: number }` — a gutter line number was activated while
-`interactiveLines` is set), `lr-highlight-activate` (`detail: { id: string }` — declared for
-parity with this library's other anchor-target viewers; not currently emitted by this component),
+`interactiveLines` is set),
 `lr-text-select` (`detail: { text, anchor, rects }` — a text selection inside the code body ended;
 `anchor` is a `line-range` anchor covering the selected lines)
 
@@ -145,10 +145,11 @@ component's own `part="pre"`/`part="code"` hooks and strips shiki's default `tab
 `<pre>`, since `[part="body"]` is already the single scrollable/focusable region (`role="group"`,
 `tabindex="0"`) for the code area. Dark mode is handled via shiki's own "dual themes" feature: every
 token carries its light color as a plain inline `color`/`background-color` and its dark color in
-`--shiki-dark`/`--shiki-dark-bg` custom properties, which an `!important` media-query rule in
-`code-block.styles.ts` reassigns under `prefers-color-scheme: dark` — the one deliberate exception in
-this component to every other color being a `--lr-*` token, since these values come from shiki's own
-theme data.
+`--shiki-dark`/`--shiki-dark-bg` custom properties. The component watches its resolved Lyra theme
+tokens and sets `data-dark-theme="true"` on the code body when the effective surface is dark; an
+`!important` state rule then activates Shiki's dark values. This follows explicit Lyra theme
+overrides instead of consulting `prefers-color-scheme` directly. Shiki's generated colors are the
+one deliberate exception to every other color being a `--lr-*` token.
 
 **Known gotchas:**
 - `copyable` defaults to `true` and reflects — see the property note above about overriding it with a

package/llms/components/lr-code-editor.md

@@ -6,6 +6,7 @@
 - **Class** `LyraCodeEditor`, also available unregistered from `@aceshooting/lyra-ui/components/forms/code-editor/code-editor.class.js`
 - **Family** `components/forms/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 8 parts, 3 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`
 
 ---
@@ -70,3 +71,8 @@ spaces — the Tab key keeps inserting `tabSize` spaces in that case.
   editor) re-arms Tab indentation.
 - The host gets a `data-invalid` attribute once the field has been blurred at least once and
   validity fails; the styles hang the danger border off it.
+
+**Additional API surface:**
+
+- `selectionDirection` — The current selection direction of the internal editing surface. Type: `'forward' | 'backward' | 'none'`.
+- `click()` — Activates the internal editing surface.

package/llms/components/lr-color-picker.md

@@ -6,6 +6,7 @@
 - **Class** `LyraColorPicker`, also available unregistered from `@aceshooting/lyra-ui/components/forms/color-picker/color-picker.class.js`
 - **Family** `components/forms/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 6 parts, 4 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`
 
 ---
@@ -25,3 +26,10 @@ parts:** `form-control`, `form-control-label` (the label; `label` is an alias ke
 **Themeable custom properties:** `--lr-color-picker-swatch-size` — the swatch's inline and block size,
 auto-swapped per `size` tier (default `'m'` reads `2.5rem`, `'2xs'` reads `1.25rem`, etc.), matching
 the size ladder `lr-input` uses.
+
+**Additional API surface:**
+
+- `click()` — Activates the internal color input.
+- `--lr-color-picker-gap` — Gap between field chrome. Default: `var(--lr-space-xs)`.
+- `--lr-color-picker-radius` — Swatch corner radius. Default: `var(--lr-radius)`.
+- `--lr-color-picker-hover-border-color` — Hover border color. Default: `var(--lr-color-brand)`.

package/llms/components/lr-combobox.md

@@ -6,6 +6,7 @@
 - **Class** `LyraCombobox`, also available unregistered from `@aceshooting/lyra-ui/components/forms/combobox/combobox.class.js`
 - **Family** `components/forms/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 22 parts, 14 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Documented with** `lr-option` (same section below)
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
@@ -53,14 +54,23 @@ shared `FormAssociated` mixin — see gotchas).
   shown when `maxRender` caps the row list; `{n}` is replaced with the hidden count)
 - `filter: OptionFilter | null = null` (attribute: false — `(option, query) => boolean`; default
   matches `label`/`searchText` case-insensitively; ignored while `source` is set)
-- `source: ComboboxSource | null = null` (attribute: false — `(query: string) =>
-  Promise<ComboboxSourceRow[]>`; when set, replaces the light-DOM `<lr-option>` list with an async
-  lookup, debounced ~200ms after each keystroke and re-run on clear/pick. `loadingText` is shown
-  while a call is in flight; a stale in-flight call that resolves after a newer one (or after
-  disconnect) is dropped via a monotonic token)
+- `source: ComboboxSource | null = null` (attribute: false — `(query: string, options: { signal:
+  AbortSignal }) => Promise<ComboboxSourceRow[]>`; when set, replaces the light-DOM `<lr-option>`
+  list with an async lookup, debounced by `sourceDelay` ms after each keystroke and re-run on
+  clear/pick. Forward `options.signal` to `fetch(url, { signal })` to cancel the request when a
+  newer query supersedes it or the element disconnects. `loadingText` is shown while a call is in
+  flight; a stale in-flight call that resolves after a newer one (or after disconnect) is dropped
+  via a monotonic token. The exported type requires the `options` parameter; an existing
+  one-parameter `(query) => …` function remains assignable under TypeScript's ordinary function
+  parameter compatibility, but consumers that need cancellation should accept and forward
+  `options.signal`.)
+- `sourceDelay: number = 200` (attribute `source-delay` — debounce in ms between the last keystroke
+  and the `source` call; `0` fires on every keystroke. Sanitized to a finite non-negative duration,
+  falling back to `200` for a non-finite value)
 - `maxRender: number = 200` (attribute `max-render` — caps how many rows render at once, always
   keeping the current selection visible even if it's outside the cap; the excess renders as one
-  `overflowText` row instead of being dropped silently)
+  `overflowText` row instead of being dropped silently. See "Large option lists" below for how to
+  size it, and when `source` is the better answer)
 - `value: string | string[]` — a getter/setter: plain `string` in single mode, `string[]` in
   `multiple` mode
 - `selectedRows: ComboboxSourceRow[]` (read-only getter) — structured rows for the current
@@ -81,11 +91,16 @@ The light-DOM `<lr-option>` path normalizes its supported label/sub/dot/group fi
 internal row model.
 
 **Events:** typing in the filter exposes the original bubbling/composed, non-cancelable `InputEvent`
-as exactly one host `input` event and does not fire `change`. An actual user selection mutation —
-pointer or keyboard selection, multiple-value toggle, tag/Backspace removal, or clear — emits exactly
-one bubbling/composed, non-cancelable plain `input` `Event`, immediately followed by the same shape
-of `change` `Event`. Re-picking the current single value and programmatic/default/reset/restore
-writes are silent. The clear button emits one `lr-clear` after its `input`/`change` pair.
+as exactly one host `input` event (no `value` detail) and does not fire `change`. An actual user
+selection mutation — pointer or keyboard selection, multiple-value toggle, tag/Backspace removal, or
+clear — emits exactly one bubbling/composed, non-cancelable `input` `CustomEvent`, immediately
+followed by the same shape of `change`, then a prefixed `lr-change` alias. All three carry
+`detail: { value }` — the new committed selection (a string in single mode, a `string[]` in
+`multiple` mode). `lr-change` mirrors `<lr-checkbox>`'s namespaced alias; subscribe to it when you
+want a `lr-`-prefixed event, or to the native-style `input`/`change` for parity with a native
+control. Re-picking the current single value and programmatic/default/reset/restore writes are
+silent (including on `lr-change`). The clear button emits one `lr-clear` after its
+`input`/`change`/`lr-change` triple.
 `lr-filter` (`detail: { value: string }`) reports the in-progress filter text on every user-driven
 keystroke — the live as-you-typed search string, deliberately *not* `value`, which is the committed
 selection. It is the supported way to read that text; reaching into the shadow root for
@@ -102,8 +117,8 @@ The internal input's `focus` and `blur` are re-dispatched as bubbling, composed
 committed selection and an in-progress filter query, so the button renders whenever either has
 something to clear, and one press clears both:
 
-- Clearing a selection emits `input`, then `change`, then `lr-clear` — and, if the query was also
-  non-empty, `lr-filter` with an empty `value`.
+- Clearing a selection emits `input`, then `change`, then `lr-change`, then `lr-clear` — and, if the
+  query was also non-empty, `lr-filter` with an empty `value`.
 - A **query-only** clear (nothing selected, just typed text) emits `lr-filter` with an empty
   `value` and deliberately **no** `change` and **no** `lr-clear`. There was no selection
   transition to report, so announcing one would be a lie. Don't listen for `lr-clear` to detect
@@ -113,6 +128,32 @@ something to clear, and one press clears both:
   selected label rather than the query, so a stale query alone never surfaces a button offering to
   clear text the user cannot see.
 
+**Large option lists: sizing `maxRender`, and why the listbox is not windowed.** Every row that
+survives the filter and fits under `maxRender` is a real DOM element — the listbox renders its rows
+in full rather than recycling a small window of them across a scroll. That is a deliberate
+accessibility constraint, not an omission: the filter input carries `aria-activedescendant`, which
+is an **IDREF**, and an IDREF only resolves within its own tree scope. Moving the rows into the
+library's windowing primitive (`<lr-virtual-list>`) would place them one shadow root deeper than the
+input that has to point at them, where neither the attribute nor its `ariaActiveDescendantElement`
+element-reflection replacement can reach — element reflection resolves same-root or upward only. So
+`<lr-virtual-list>` stays `role="list"`/`role="listitem"` and is the right tool for feeds and
+viewers, not for a listbox whose active row must stay addressable.
+
+What that means in practice:
+
+- **Up to a few hundred rows, raise `maxRender` and move on.** A few hundred flex rows is an
+  unremarkable amount of DOM; a country, currency, or time-zone list (typically 200–450 entries)
+  renders comfortably with `max-render` set to cover it. The cap exists to bound pathological
+  cases, not to make lists of that size expensive.
+- **Past roughly a thousand rows, reach for `source` instead of a larger cap.** An async source
+  narrows the candidate set before it ever becomes DOM, which is a categorically better trade than
+  rendering everything and asking the browser to lay it out. Pair it with `sourceDelay` to debounce.
+- **Leave the overflow row doing its job.** When the cap does bite, the excess collapses into one
+  `overflowText` row (default `"+{n} more — refine your search"`) rather than disappearing
+  silently, and the current selection is always kept visible even when it falls outside the cap.
+  Suppressing that row by setting `maxRender` far above the real list size trades a useful "keep
+  typing" affordance for layout work no user asked for.
+
 **Slots:** default (`<lr-option>` children), `label`, `hint`, `error` (overrides the `errorText`
 attribute when provided), plus two adornment slots:
 - `start` — content at the inline-start of the trigger row, before the selected-value tags and the
@@ -142,6 +183,14 @@ a hovered or keyboard-active `[part='option']` row — the same per-component in
 `lr-select`'s identical `--lr-select-option-active-bg` uses, so a consumer can retheme just this
 row state without hijacking the shared `--lr-color-brand-quiet` token library-wide.
 
+The currently-**selected** row (`[part='option'][aria-selected='true']`) has its own matching set:
+`--lr-combobox-option-selected-bg` (default `transparent`), `--lr-combobox-option-selected-border`
+and `--lr-combobox-option-selected-color` (both default `var(--lr-color-brand)`), and
+`--lr-combobox-option-selected-font-weight` (default `var(--lr-font-weight-semibold)`) — the same
+four-token indirection `lr-select`/`lr-model-select` already provide for their own selected row.
+Like the active-bg knob these are inline `var()` fallbacks, not declared on `:host`, so a consumer
+can retheme the selected row without hijacking `--lr-color-brand` library-wide.
+
 `--lr-combobox-trigger-height` pins an **exact** input-container height (both floors and caps it),
 for pixel-matching an `<lr-input>` or `<lr-select>` in the same toolbar row. It is **undeclared by
 default**, leaving `--lr-combobox-trigger-min-height` as a floor only and the row free to grow —
@@ -203,7 +252,7 @@ Session-history/autofill state is stored as a name-independent JSON string array
 array restores the selection (single mode keeps its first entry); malformed or wrong-shape state
 restores an empty selection. Restored state wins even when it arrives before the first option
 collection, while `form.reset()` still returns to the declarative selected default. Restoration is
-synchronous and fires no `input`/`change` event.
+synchronous and fires no `input`/`change`/`lr-change` event.
 
 **Known gotchas:**
 - `with-clear` remains supported for compatibility, but new code should use the mirrored
@@ -231,4 +280,8 @@ synchronous and fires no `input`/`change` event.
   `form.reset()` default itself is captured exclusively from that very first pass; a later pick, or
   a later batch of newly-`selected` options, never redefines what a reset restores to.
 
+**Additional API surface:**
+
+- `part="tag-label"` — The wrapping/ellipsis-safe selected-tag label.
+
 ---

package/llms/components/lr-command-palette.md

@@ -6,6 +6,7 @@
 - **Class** `LyraCommandPalette`, also available unregistered from `@aceshooting/lyra-ui/components/layout/command-palette/command-palette.class.js`
 - **Family** `components/layout/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 14 parts, 8 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`
 
 ---
@@ -59,3 +60,10 @@ of use rather than a `:host` declaration, so it can be set on the element *or on
 after `::part()`), so highlighting the active row previously required hijacking the library-wide
 `--lr-color-brand-quiet` token and repainting everything else that read it. Unset, it falls back to
 that token, so rendering is unchanged.
+
+**Additional API surface:**
+
+- `part="command-group"` — A labeled ARIA group containing visible command options.
+- `part="list-spacer"` — Virtual result extent inside the scrolling list.
+- `--lr-command-palette-row-height` — Virtual command-row height. Default: `var(--lr-size-3rem)`.
+- `--lr-command-palette-group-height` — Virtual group-heading height. Default: `var(--lr-size-2rem)`.

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

@@ -6,6 +6,7 @@
 - **Class** `LyraCommitCard`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/commit-card/commit-card.class.js`
 - **Family** `components/agent-tools/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 17 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`
 
 ---

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

@@ -6,6 +6,7 @@
 - **Class** `LyraCommunityCard`, also available unregistered from `@aceshooting/lyra-ui/components/retrieval/community-card/community-card.class.js`
 - **Family** `components/retrieval/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 11 parts, 0 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`
 
 ---

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

@@ -6,6 +6,7 @@
 - **Class** `LyraComparePanel`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/compare-panel/compare-panel.class.js`
 - **Family** `components/agent-tools/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 9 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`
 
 ---
@@ -21,7 +22,8 @@ recorded winner, host-writable to reflect a previously-recorded vote back. `item
 (attribute `item-id`) — an opaque id round-tripped through `lr-vote`. `hideTie: boolean = false`
 (attribute `hide-tie`) and `hideBothBad: boolean = false` (attribute `hide-both-bad`) hide the
 corresponding vote button. `syncScroll: boolean = false` (attribute `sync-scroll`) links both panes'
-scroll position.
+scroll position. `disabled: boolean = false` (reflected) disables every vote button and suppresses
+`lr-vote`.
 
 **Slots:** `a` (the first output — any content, a chat message, markdown, a viewer), `b` (the second
 output), and `prompt` (optional shared-input header above both panes).

package/llms/components/lr-confirm-bar.md

@@ -6,6 +6,7 @@
 - **Class** `LyraConfirmBar`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/confirm-bar/confirm-bar.class.js`
 - **Family** `components/agent-tools/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 19 parts, 5 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`
 
 ---

package/llms/components/lr-contact-viewer.md

@@ -6,6 +6,7 @@
 - **Class** `LyraContactViewer`, also available unregistered from `@aceshooting/lyra-ui/components/viewers/contact-viewer/contact-viewer.class.js`
 - **Family** `components/viewers/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 10 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`
 
 ---
@@ -20,7 +21,12 @@ label when `FN` is absent).
 Remote resources are capped at 25 MB; exceeding it surfaces the localized
 `documentPreviewResourceTooLarge` message instead of the contacts.
 
-**Properties:** `src`, `name`, and `maxHeight` (attribute `max-height`) are strings.
+**Properties:** `src`, `name`, and `maxHeight` (attribute `max-height`) are strings. A host
+`aria-label` takes precedence over `name`. `highlights`, `activeHighlightId`, `anchor`, and
+`anchorKinds` (`['text-quote', 'fragment']`) provide the shared text-viewer contract.
+
+**Methods:** `search(query)`, `searchNext()`, `searchPrevious()`, `clearSearch()`, and
+`scrollToAnchor()` operate on rendered contact text and emit the shared search/anchor events.
 
 **Events:** `lr-render-error` with `detail.error` when fetching or parsing fails.
 

package/llms/components/lr-context-inspector.md

@@ -6,6 +6,7 @@
 - **Class** `LyraContextInspector`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/context-inspector/context-inspector.class.js`
 - **Family** `components/agent-tools/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 15 parts, 0 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`
 
 ---

package/llms/components/lr-context-meter.md

@@ -6,6 +6,7 @@
 - **Class** `LyraContextMeter`, also available unregistered from `@aceshooting/lyra-ui/components/data/context-meter/context-meter.class.js`
 - **Family** `components/data/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 7 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`
 
 ---
@@ -63,10 +64,12 @@ capacity), `segment` (one occupied segment — carries `data-tone` and, for cust
 <lr-context-meter variant="ring" total="128000" .segments=${segments}></lr-context-meter>
 ```
 
-`role="img"` and a computed `aria-label` are set imperatively on the *host* element itself in
-`willUpdate` (mirroring `lr-gauge`'s "meter" role convention) — every internal node (`track`,
-`segment`, the ring's `<svg>`, `label`) is `aria-hidden`, so a screen reader gets one meaningful
-summary string instead of the raw markup. That summary's "used" figure is the sum of
+An internal visually-hidden semantic node carries `role="meter"` plus `aria-valuenow`,
+`aria-valuemin`, and `aria-valuemax` whenever `total > 0`; without a valid positive total it uses
+`role="group"` and omits numeric meter attributes. Its accessible name is the host `aria-label`
+when present, otherwise the generated summary. A separate visually-hidden segment list exposes
+each labeled quantity, while the visible track, segments, ring SVG, and visible label remain
+`aria-hidden`. The summary's "used" figure is the sum of
 `segments[].value`, clamped to `total` whenever `total > 0` so the announced text can never claim
 more than 100% used (e.g. `segments` summing to `150000` against `total="128000"` still announces
 `"128,000 of 128,000 used"`) — matching what the *visual* meter shows, since each segment's ratio is
@@ -80,8 +83,8 @@ numbers, so the two circular-meter components in the library share one visual sc
 
 **Known gotchas:**
 - The ring variant's per-segment `<title>` and the bar variant's per-segment `title=` attribute are
-  native mouse-hover tooltips only — they sit inside `aria-hidden` markup, so screen readers never
-  read them; only the host's own `role="img"`/`aria-label` carries accessible information.
+  native mouse-hover tooltips only — they sit inside `aria-hidden` markup. Screen readers use the
+  hidden meter/group summary and segment list instead.
 - `variant="ring"` fixes the host at `8em × 8em` (`:host([variant='ring'])`) — the bar variant's
   `inline-size: 100%` does not apply in ring mode; resize it via `font-size` or an explicit
   width/height override on the host instead.
@@ -89,4 +92,10 @@ numbers, so the two circular-meter components in the library share one visual sc
   `segments` render further around the circle (starting at 12 o'clock, going clockwise); there's no
   independent sort/z-order control.
 
+**Additional API surface:**
+
+- `part="segment-item"` — One visually-hidden segment label/count pair.
+- `part="segment-list"` — The visually-hidden list exposing the segment breakdown.
+- `part="semantic"` — The visually-hidden meter/group carrying aggregate range semantics.
+
 ---

package/llms/components/lr-control-group.md

@@ -6,6 +6,7 @@
 - **Class** `LyraControlGroup`, also available unregistered from `@aceshooting/lyra-ui/components/layout/control-group/control-group.class.js`
 - **Family** `components/layout/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 1 part, 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`
 
 ---

package/llms/components/lr-conversation-item.md

@@ -6,6 +6,7 @@
 - **Class** `LyraConversationItem`, also available unregistered from `@aceshooting/lyra-ui/components/conversation/conversation-item/conversation-item.class.js`
 - **Family** `components/conversation/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 12 parts, 7 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`
 
 ---
@@ -73,8 +74,8 @@ in-place rename `<input>`'s own `focus`, for the same reason as `blur`)
 
 `leading`/`content`/`excerpt`/`meta` must all stay non-focusable — see the `role="button"` note below.
 
-**CSS parts:** `base`, `option`, `content`, `title`, `title-input`, `rename-button`, `excerpt`,
-`timestamp`, `actions`
+**CSS parts:** `base`, `active-indicator` (decorative, rendered only while `active`), `option`,
+`content`, `title`, `title-input`, `rename-button`, `excerpt`, `timestamp`, `actions`
 
 **Themeable custom properties:** `--lr-conversation-item-active-bg` (default
 `var(--lr-color-brand-quiet)`) — the row's background while `active`. `--lr-conversation-item-active-color`
@@ -93,6 +94,13 @@ the default active background; keep any override at 4.5:1 or better against it.
 custom active background needs its own title color set alongside them, or the title drops below
 contrast while the excerpt stays legible.
 
+`--lr-conversation-item-active-indicator-color` (default `var(--lr-color-brand)`) controls the
+decorative `active-indicator` part's color. `--lr-conversation-item-active-indicator-width`
+(default `var(--lr-size-2px)`) controls its inline width. `--lr-conversation-item-active-indicator-inset-inline`
+(default `0 auto`) controls its logical inline insets; set `auto 0` to move the indicator to
+inline-end. The indicator is `aria-hidden`, occupies the full row block-size, and is absent while
+the row is inactive.
+
 `--lr-conversation-item-compact-padding` (default `var(--lr-space-xs) var(--lr-space-s)`) —
 `[part='base']`'s padding while `compact`. `--lr-conversation-item-compact-gap` (default
 `var(--lr-space-2xs)`) — `[part='base']`'s gap while `compact`. Like the active-state pair, both are

package/llms/components/lr-copy-button.md

@@ -6,6 +6,7 @@
 - **Class** `LyraCopyButton`, also available unregistered from `@aceshooting/lyra-ui/components/utility/copy-button/copy-button.class.js`
 - **Family** `components/utility/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 1 part, 0 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`
 
 ---
@@ -49,4 +50,8 @@ buttons, this has no code/JSON content model to adopt just to reuse the copy aff
   and some engines throw synchronously rather than rejecting — either way `lr-copy` still fires
   with the intended text so a consumer can always show its own confirmation/fallback UI.
 
+**Additional API surface:**
+
+- `click()` — Activates the native button, matching the host focus/blur forwarding contract.
+
 ---

package/llms/components/lr-csv-viewer.md

@@ -6,6 +6,7 @@
 - **Class** `LyraCsvViewer`, also available unregistered from `@aceshooting/lyra-ui/components/viewers/csv-viewer/csv-viewer.class.js`
 - **Family** `components/viewers/` — see `llms/index.md` for its siblings
 - **Optional peers** `papaparse` — see `llms/peers.md`
+- **Themeable via** 11 parts, 2 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`
 
 ---
@@ -38,9 +39,11 @@ Enter/Space. `lr-anchor-result` (`detail: { found }`) — fired after an `anchor
 `scrollToAnchor()` call. `lr-search-change` (`detail: { query, matchCount, activeIndex }`) — from
 `search()`/`searchNext()`/`searchPrevious()`/`clearSearch()`.
 
-**CSS parts:** `base`, `sheet`, `header-row`, `data-row`, `cell`, `cell-highlight` (a cell covered by
-a `highlights` entry), `rows`, `spinner`, and `error`. `data-row`, `cell` and `cell-highlight` are
-rendered inside the internal `<lr-virtual-list>` and forwarded via `exportparts`, so
+**CSS parts:** `base`, `sheet`, `header-row`, `data-row`, `cell`, `cell-highlight` (a structural
+cell covered by a `highlights` entry), `cell-highlight-action` (the native button filling a
+highlighted cell; emits `lr-highlight-activate`), `rows`, `spinner`, and `error`. `data-row`,
+`cell`, `cell-highlight`, and `cell-highlight-action` are rendered inside the internal
+`<lr-virtual-list>` and forwarded via `exportparts`, so
 `lr-csv-viewer::part(cell)` reaches them from a consumer stylesheet.
 
 **Themeable custom properties:** `--lr-csv-viewer-max-height` (default `none`) — maximum block size

package/llms/components/lr-dashboard-grid.md

@@ -6,6 +6,7 @@
 - **Class** `LyraDashboardGrid`, also available unregistered from `@aceshooting/lyra-ui/components/layout/dashboard-grid/dashboard-grid.class.js`
 - **Family** `components/layout/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 5 parts, 5 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`
 
 ---
@@ -35,3 +36,7 @@ overriding them from a stylesheet has no effect — set the properties instead.
 (default `var(--lr-color-border-strong)`) retints the mouse-hover outline on `[part='cell']` — a
 preview of its own `:focus-visible` ring, shown because every cell is a real focusable,
 draggable/resizable target; set it to `transparent` to opt out of the hover treatment entirely.
+
+**Additional API surface:**
+
+- `--lr-dashboard-grid-collision-outline-color` — Outline color of a cell whose current drag/resize preview collides with another cell. Default: `var(--lr-color-danger)`.