@aceshooting/lyra-ui 6.0.0 → 6.2.0

package/llms/components/lr-button.md

@@ -6,6 +6,7 @@
 - **Class** `LyraButton`, also available unregistered from `@aceshooting/lyra-ui/components/forms/button/button.class.js`
 - **Family** `components/forms/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 5 parts, 28 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`
 
 ---
@@ -16,7 +17,27 @@ A generic action-button primitive. Renders an internal native `<button>`; `type=
 `type="reset"` are handled by the component itself via the host's own `closest('form')`, since a
 shadow-internal native button doesn't participate in an ancestor form's submission on its own.
 
+Set `href` to a safe link URL and the root renders as a real `<a part="base" href=…>` instead — a
+link styled as a button (e.g. a CTA). Native navigation is then the activation, so the submit/reset
+handling and `type` have no effect in that mode. A disabled link button (its own `disabled` or an
+ancestor `<fieldset disabled>`) renders the anchor with `aria-disabled="true"` and **no `href`**, so
+it is neither focusable nor navigable; an unsafe/unparseable `href` falls back to the native
+`<button>`.
+
 **Properties:**
+- `href?: string` — when set to a safe link URL (`http:`/`https:`/`blob:`/`mailto:`/relative; see
+  `safeLinkHref`), the root renders as an `<a href=…>` instead of a `<button>`. Setting `download`
+  narrows the allowlist to `http:`/`https:`/`blob:`/relative — `mailto:` names no retrievable bytes,
+  so a `mailto:` href paired with `download` falls back to the native `<button>`. Unset (the default)
+  renders a plain `<button>`, unchanged. `type` (submit/reset) has no effect while the anchor
+  renders. While the button is disabled the anchor is rendered **without** `href` (keeping
+  `aria-disabled="true"`), so a disabled link button cannot navigate. An unsafe/unparseable value
+  falls back to the native `<button>`
+- `target?: string` — native anchor `target`, used only while `href` resolves to a link. Setting it
+  (e.g. `'_blank'`) automatically derives `rel="noopener noreferrer"` on the anchor; `rel` is never
+  independently settable (reverse-tabnabbing). Ignored in `<button>` mode
+- `download?: string` — native anchor `download` attribute, used only while `href` resolves to a
+  link. Ignored in `<button>` mode
 - `variant: 'neutral' | 'brand' | 'success' | 'warning' | 'danger' = 'neutral'` (reflected)
 - `appearance: 'accent' | 'filled' | 'outlined' | 'plain' | 'quiet' | 'link' = 'filled'` (reflected)
   — `'accent'` is a
@@ -41,15 +62,17 @@ shadow-internal native button doesn't participate in an ancestor form's submissi
 The shared `m` size uses `--lr-font-size-m`. The internal button follows the host's inline size through `--lr-button-width` (default
 `100%`), and each size tier's `min-block-size` floor is exposed as its own token (see below).
 
-**Getters/methods:** `click()`, `focus(options?)`, and `blur()` — forwarded to the internal native
-`<button>`; `click()` also runs the component's submit/reset behavior.
+**Getters/methods:** `click()`, `focus(options?)`, and `blur()` — forwarded to the internal base
+element (the `<button>`, or the `<a>` in anchor mode); `click()` also runs the component's
+submit/reset behavior in `<button>` mode.
 
 **Events:** none (a plain native `click` bubbles and composes through the shadow boundary
 unmodified; disabled while `disabled` or `loading`).
 
 **Slots:** default (label content), `start` (leading icon/content), `end` (trailing icon/content).
 
-**CSS parts:** `base`, `label`, `start`, `end`, `spinner` (present only while `loading`).
+**CSS parts:** `base` (the internal native `<button>`, or an `<a>` when `href` resolves to a safe
+link), `label`, `start`, `end`, `spinner` (present only while `loading`).
 
 **Themeable custom properties:** `--lr-button-width`, `--lr-button-accent`, `--lr-button-fill`,
 `--lr-button-on-fill`, `--lr-button-border` (each swapped by the active `variant`, default
@@ -77,6 +100,9 @@ and the per-`size`
 and any slotted content) and `--lr-button-radius` (default `--lr-radius`, the corner radius) are
 both retunable without a `::part(base)` rule but — unlike the four size knobs below — do not vary
 by `size` tier; `appearance="link"` ignores `--lr-button-radius` (it renders with zero radius).
+`--lr-button-shadow` is **undeclared by default**, so `box-shadow` falls back to `none` —
+byte-identical to before this property existed — set it to add a drop shadow (e.g. an
+elevated/floating action button) without a `::part(base)` rule.
 
 **Retuning one `size` tier's geometry, without a `::part(base)` rule.** Four more properties carry
 the active tier's geometry, and every `:host([size='…'])` rule does nothing but re-assign them — no

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

@@ -6,6 +6,7 @@
 - **Class** `LyraCalendarViewer`, also available unregistered from `@aceshooting/lyra-ui/components/viewers/calendar-viewer/calendar-viewer.class.js`
 - **Family** `components/viewers/` — see `llms/index.md` for its siblings
 - **Optional peers** `ical.js` — see `llms/peers.md`
+- **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`
 
 ---
@@ -15,7 +16,12 @@
 Fetches and parses `.ics` calendars with the optional `ical.js` peer and renders each VEVENT as
 plain text, including its title, start/end time, location, and description. No HTML is injected.
 
-**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 event text and emit `lr-search-change`/`lr-anchor-result`.
 
 **Events:** `lr-render-error` with `detail.error` when fetching or parsing fails.
 

package/llms/components/lr-calendar.md

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

package/llms/components/lr-callout.md

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

package/llms/components/lr-card.md

@@ -6,6 +6,7 @@
 - **Class** `LyraCard`, also available unregistered from `@aceshooting/lyra-ui/components/layout/card/card.class.js`
 - **Family** `components/layout/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 6 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`
 
 ---
@@ -30,6 +31,11 @@ to `<wa-card>`'s contract, staying slot-compatible with `lr-result-card` where t
   reproduces a plain static card: no `tabindex`, no listeners, no events.
 - `href?: string` — when set, the card's root renders as a real `<a href=...>` instead of a `<div>`,
   for a whole-card link (e.g. a wide CTA tile). Unset (the default) renders a plain `<div>`.
+- `target?: string` — native anchor target, applied only while `href` resolves to a link. Setting it
+  to `'_blank'` (or any other target) automatically derives `rel="noopener noreferrer"` on the
+  rendered anchor; there is deliberately **no** separately-settable `rel` property, so a consumer
+  can't forget it and leave the opened page holding a `window.opener` back-reference
+  (reverse-tabnabbing). Unset (the default) emits neither `target` nor `rel`.
 
 **Events:** `lr-card-activate` (no detail) — the whole card was activated, by click or by
 Enter/Space while `[part='base']` has focus. Only fired while `interactive` is set **without**

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

@@ -6,6 +6,7 @@
 - **Class** `LyraCarouselItem`, also available unregistered from `@aceshooting/lyra-ui/components/layout/carousel/carousel-item.class.js`
 - **Family** `components/layout/` — 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`
 
 ---

package/llms/components/lr-carousel.md

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

package/llms/components/lr-chart.md

@@ -5,7 +5,8 @@
 - **Import** `import '@aceshooting/lyra-ui/components/charts/chart/chart.js';` (registers the tag; side-effect import)
 - **Class** `LyraChart`, also available unregistered from `@aceshooting/lyra-ui/components/charts/chart/chart.class.js`
 - **Family** `components/charts/` — see `llms/index.md` for its siblings
-- **Optional peers** `chart.js`, `chartjs-plugin-zoom` — see `llms/peers.md`
+- **Optional peers** `chart.js`, `chartjs-plugin-datalabels`, `chartjs-plugin-zoom` — see `llms/peers.md`
+- **Themeable via** 7 parts, 6 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`
 
 ---
@@ -24,15 +25,27 @@ Chart.js wrapper every other `lr-*-chart` tag subclasses; supports both a simpli
 - `labels: string[] = []` (attribute: false)
 - `datasets: Series[] = []` (attribute: false) — `Series { label: string; data?: (number|null)[];
   points?: {x,y,label?}[]; color?: string|string[]; fill?: boolean; width?: number; dash?: boolean;
-  noTooltip?: boolean; axis?: 'y'|'y2'; pointColors?: string[]; pointRadius?: number; type?:
-  'line'|'bar' }`
+  noTooltip?: boolean; axis?: 'y'|'y2'; pointColors?: string[]; pointRadius?: number|number[];
+  segmentColors?: string[]; type?: 'line'|'bar' }`
+  - `pointRadius` takes a single number (applied to every point) **or** an array matching `data`'s
+    length that sizes each point independently — passed straight through to Chart.js, which
+    supports both natively. Useful for emphasizing a single outlier or the latest reading without
+    splitting the series in two.
+  - `segmentColors` colors each *segment* (the line drawn between two consecutive points) by the
+    segment's **starting** point index, so `['red', 'green']` over 3 points paints the first
+    segment red and the second green; a shorter array cycles. Wired to Chart.js's
+    `segment.borderColor` scriptable option, so it is only meaningful for line-type series.
+    Typical use is threshold/anomaly banding along one line. A series that omits it (or passes an
+    empty array) emits no `segment` key at all, leaving line rendering exactly as before.
 - `legend: boolean = false`
 - `legendPosition: LyraChartLegendPosition = 'top'` (attribute `legend-position`) — places the
   legend at `top`, `right`, `bottom`, or `left`; `auto` chooses right above 480px and bottom below
   that allocation width
-- `valueFormatter?: LyraChartValueFormatter` (attribute: false) — formats numeric tick, tooltip,
-  and legend values; the callback receives the value and `'tick'`, `'tooltip'`, or `'legend'`
-  context
+- `valueFormatter?: LyraChartValueFormatter` (attribute: false) — formats numeric (value-axis)
+  tick, tooltip, and legend values; the callback receives the value and `'tick'`, `'tooltip'`, or
+  `'legend'` context. Never runs against the categorical x-axis's own labels (line/bar's `labels`
+  strings) — Chart.js's category scale passes the tick index to `ticks.callback`, not the label
+  text
 - `area: boolean = false`
 - `zoom: boolean = false` — wheel/drag/pinch zoom on the `x` axis only (pan disabled, and the zoom
   range is limited to the original data extent); shows the `reset-zoom-button` while zoomed
@@ -46,6 +59,16 @@ Chart.js wrapper every other `lr-*-chart` tag subclasses; supports both a simpli
 - `stacked: boolean = false` — stacks the `x`/`y`(/`y2`) scale entries `buildScales()` returns; only
   meaningful for `bar`/`line` types (scatter/bubble's linear `x` scale and the radial `r` scale used
   by radar/polar-area are out of scope)
+- `dataLabels: boolean = false` (attribute `data-labels`) — draws each point's value on the chart via
+  the optional `chartjs-plugin-datalabels` peer (see `peers.md`). Unset (the default) leaves labels
+  off; because the plugin is registered **per chart instance** (not globally), a `<lr-chart
+  data-labels>` never affects any other chart on the page. If the peer is not installed the chart
+  still renders and the attribute is inert, with one `console.warn`. The screen-reader equivalent is
+  the always-present accessible data table (`show-data-table` makes it visible) — labels are a
+  purely visual, canvas-only addition and add no new a11y surface.
+- `stackTotals: boolean = false` (attribute `stack-totals`) — with `stacked` (bar/line only), draws
+  the per-category stack total above each stack, via the same `chartjs-plugin-datalabels` peer.
+  Null/undefined points are skipped; a category whose every value is null shows no total (not `0`)
 - `config?: Partial<ChartConfiguration>` (attribute: false) — deep-merged over the generated
   config; any nested key wins without clobbering sibling generated keys. This is the raw Chart.js
   escape hatch, so a caller-supplied `config.type` is passed through rather than normalized.
@@ -58,11 +81,25 @@ Chart.js wrapper every other `lr-*-chart` tag subclasses; supports both a simpli
 - `chartArea: LyraChartArea | undefined` (readonly) — current Chart.js chart-area geometry in
   canvas-local coordinates (`top`, `left`, `right`, `bottom`, `width`, `height`), when a chart is
   drawn
+- `appendData(label, values, maxPoints?)` — appends one aligned numeric category and optionally
+  keeps only the newest `maxPoints`; point-based scatter/bubble series are left unchanged
 
-**Methods:** `resetZoom()` (reset any active zoom/pan to the original view), `refreshTheme()`
-(forces a redraw so the `--lr-chart-*` tokens below are re-read from the current computed style —
-the escape hatch for a consumer's own theme-toggle handler to call when it flips something, e.g. a
-`data-theme` attribute, that doesn't otherwise change any `lr-chart` property)
+**Methods:** `resetZoom()` (reset any active zoom/pan to the original view), `refreshTheme()`, and
+`exportData('csv' | 'png')` (returns a spreadsheet-safe CSV snapshot or the current PNG data URL
+when Chart.js is loaded)
+(forces a redraw so the `--lr-chart-*` tokens below are re-read from the current computed style. A
+built-in `ThemeWatcher` now calls this automatically when `prefers-color-scheme` flips or an
+ancestor's `class`/`style`/`data-theme`/`data-color-scheme` attribute mutates — the most common
+theme-toggle mechanisms — so a consumer rarely needs to call it by hand; it remains public as the
+escape hatch for theme changes those signals can't observe)
+
+`seriesPalette(): string[]` resolves the categorical series ramp (`--lr-color-chart-1..8`) through
+`getComputedStyle` and returns the concrete, theme-aware colors — the exact same values the chart
+hands any series that sets no `color` of its own. Call it to color chart-adjacent UI (custom
+legends, KPI tiles, annotations fed through the raw `config` passthrough) from one source of truth
+instead of hand-resolving `--lr-color-chart-N` and drifting out of sync when the theme flips.
+Returns a fresh array each call (safe to mutate), and falls back to the light-mode literals only
+when the custom properties can't be resolved at all (e.g. a detached host).
 
 **Events:** `lr-zoom` (`detail: { zoomed: boolean }`, fired on zoom-complete and on
 `resetZoom()`), `lr-point-click` (fired when a click lands on, or nearest to — intersect-only —
@@ -108,10 +145,9 @@ subset actually used.
   property values fall back to `line`. Each typed `lr-*-chart` subclass (e.g.
   `llms/components/lr-bar-chart.md`) locks its *own* `type` via a real prototype accessor — a
   genuine runtime lock, not just a compile-time default.
-- no global theme-broadcast event exists to auto-retheme an already-drawn chart on a theme switch —
-  a consumer flipping something upstream (e.g. a `data-theme` attribute) that doesn't otherwise
-  change any `lr-chart` property must call `refreshTheme()` itself to make Chart.js re-read the
-  `--lr-chart-*` tokens above.
+- a built-in `ThemeWatcher` auto-retheme an already-drawn chart when `prefers-color-scheme` flips or
+  an ancestor's `class`/`style`/`data-theme`/`data-color-scheme` attribute mutates (coalesced to one
+  redraw). `refreshTheme()` stays public for out-of-band theme changes those signals can't observe.
 - generated `scales` are keyed off the *effective* type (`config.type` ?? `type`, see
   `effectiveType()`) and are type-appropriate: no scale at all for `type="pie"`/`"doughnut"` (true of
   `<lr-chart type="pie">` directly, not just the `lr-pie-chart`/`lr-doughnut-chart` subclasses),

package/llms/components/lr-chat-composer.md

@@ -6,6 +6,7 @@
 - **Class** `LyraChatComposer`, also available unregistered from `@aceshooting/lyra-ui/components/conversation/chat-composer/chat-composer.class.js`
 - **Family** `components/conversation/` — 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`
 
 ---

package/llms/components/lr-chat-message.md

@@ -6,6 +6,7 @@
 - **Class** `LyraChatMessage`, also available unregistered from `@aceshooting/lyra-ui/components/conversation/chat-message/chat-message.class.js`
 - **Family** `components/conversation/` — 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`
 
 ---
@@ -116,6 +117,11 @@ streaming-indicator pulse animation's cycle, the same shared compound token
 background already maps to that same token, override `[part=bubble]`'s background explicitly (e.g.
 via `::part(bubble)`) so message bubbles stay visually distinct from the surrounding panel.
 
+> Retheming a bubble from outside `<lr-chat-message>` (e.g. per-thread or per-role 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. Internally renders a `<lr-live-region>` (a first-party sibling
 component, auto-imported alongside this one, not an npm peer) for the status-transition
 announcements described below.

package/llms/components/lr-chat-viewport.md

@@ -6,6 +6,7 @@
 - **Class** `LyraChatViewport`, also available unregistered from `@aceshooting/lyra-ui/components/conversation/chat-viewport/chat-viewport.class.js`
 - **Family** `components/conversation/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 5 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-checkbox-group.md

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

@@ -6,6 +6,7 @@
 - **Class** `LyraCheckbox`, also available unregistered from `@aceshooting/lyra-ui/components/forms/checkbox/checkbox.class.js`
 - **Family** `components/forms/` — 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`
 
 ---
@@ -37,6 +38,10 @@ silent. Internal `focus`/`blur` are re-dispatched as bubbling, composed host eve
 same as clicking a native checkbox's associated `<label>`. If left empty, set `aria-label` on the
 host so the control still has an accessible name.
 
+Host `aria-describedby` is forwarded to the internal `role="checkbox"`, so an externally-owned
+description can be associated with one checkbox inside a group. The attribute is omitted from the
+internal role when unset and tracks host attribute changes.
+
 **CSS parts:** `base` (the whole interactive control, `role="checkbox"`), `box` (the small square
 showing the checkmark/indeterminate dash), `checkmark` (the checkmark or indeterminate-dash glyph),
 `label` (wrapper around the default slot)

package/llms/components/lr-checkpoint.md

@@ -6,6 +6,7 @@
 - **Class** `LyraCheckpoint`, also available unregistered from `@aceshooting/lyra-ui/components/conversation/checkpoint/checkpoint.class.js`
 - **Family** `components/conversation/` — 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`
 
 ---

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

@@ -6,6 +6,7 @@
 - **Class** `LyraChipGroup`, also available unregistered from `@aceshooting/lyra-ui/components/overlays/chip/chip-group.class.js`
 - **Family** `components/overlays/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 2 parts, 0 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Documented with** `lr-chip` (same section below)
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
@@ -73,6 +74,9 @@ back to `--lr-chip-bg`), the density quintet `--lr-chip-font-size`, `--lr-chip-p
 `:host([size])` rule, so setting one directly on the element overrides that step of the scale; the
 `m` defaults are `--lr-font-size-sm` / `--lr-size-0-25rem` / `--lr-space-s` / `--lr-space-xs` /
 `--lr-font-size-sm`), the height pair `--lr-chip-min-height` / `--lr-chip-height` (below),
+`--lr-chip-radius` (default `--lr-radius-pill`, the corner radius of both `[part='base']` and
+`[part='remove-button']` — retunable without a `::part()` rule, and unlike the density quintet
+above does not vary by `size`; the same `--lr-button-radius` pattern),
 plus shared tokens (`--lr-space-xs`, `--lr-space-s`,
 `--lr-color-brand`/`-brand-quiet`, `--lr-color-success`/`-success-quiet`,
 `--lr-color-warning`/`-warning-quiet`, `--lr-color-danger`/`-danger-quiet`,

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** 4 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`
 
@@ -73,6 +74,9 @@ back to `--lr-chip-bg`), the density quintet `--lr-chip-font-size`, `--lr-chip-p
 `:host([size])` rule, so setting one directly on the element overrides that step of the scale; the
 `m` defaults are `--lr-font-size-sm` / `--lr-size-0-25rem` / `--lr-space-s` / `--lr-space-xs` /
 `--lr-font-size-sm`), the height pair `--lr-chip-min-height` / `--lr-chip-height` (below),
+`--lr-chip-radius` (default `--lr-radius-pill`, the corner radius of both `[part='base']` and
+`[part='remove-button']` — retunable without a `::part()` rule, and unlike the density quintet
+above does not vary by `size`; the same `--lr-button-radius` pattern),
 plus shared tokens (`--lr-space-xs`, `--lr-space-s`,
 `--lr-color-brand`/`-brand-quiet`, `--lr-color-success`/`-success-quiet`,
 `--lr-color-warning`/`-warning-quiet`, `--lr-color-danger`/`-danger-quiet`,

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-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`
 
 ---

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`
 
 ---

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** 7 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`
 
 ---

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, 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-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** 21 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,21 @@ 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 `options` parameter is optional in the type, so a legacy
+  `(query) => …` source stays assignable.)
+- `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 +89,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 +115,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 +126,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
@@ -132,13 +171,24 @@ indicator from `maxRender`), `error`, `hint`
 **Themeable custom properties:** `--lr-combobox-trigger-padding`,
 `--lr-combobox-trigger-min-height`, `--lr-combobox-font-size`, `--lr-combobox-tag-padding`,
 `--lr-combobox-tag-font-size`, and `--lr-combobox-expand-size` (the decorative icon box; each
-standard size supplies an aligned default), plus shared tokens.
+standard size supplies an aligned default), plus shared tokens. `--lr-combobox-gap` (default
+`--lr-space-xs`, the gap inside `[part='combobox']`) and `--lr-combobox-radius` (default
+`--lr-radius`, its corner radius) are both retunable without a `::part(combobox)` rule but, unlike
+the properties above, do not vary by `size` — the same `--lr-button-gap`/`-radius` pattern.
 
 `--lr-combobox-option-active-bg` (default `var(--lr-color-brand-quiet)`) recolors the background of
 a hovered or keyboard-active `[part='option']` row — the same per-component indirection
 `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 —
@@ -200,7 +250,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

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** 11 parts, 6 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-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`
 
 ---