@aceshooting/lyra-ui 6.1.0 → 7.0.0

package/llms/components/lr-breadcrumb.md

@@ -6,6 +6,7 @@
 - **Class** `LyraBreadcrumb`, also available unregistered from `@aceshooting/lyra-ui/components/layout/breadcrumb/breadcrumb.class.js`
 - **Family** `components/layout/` — 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-breadcrumb-item` (same section below)
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
@@ -37,3 +38,7 @@ set on the item, on `<lr-breadcrumb>`, or on any ancestor above the trail:
 `::part()`), so tinting the current item previously meant overriding the library-wide
 `--lr-color-text-quiet` token and repainting everything else that read it. Unset, it falls back to
 that token.
+
+**Additional API surface:**
+
+- `part="separator"` — Decorative separator shown before non-first items.

package/llms/components/lr-browser-frame.md

@@ -6,6 +6,7 @@
 - **Class** `LyraBrowserFrame`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/browser-frame/browser-frame.class.js`
 - **Family** `components/agent-tools/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 11 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`
 
 ---
@@ -49,3 +50,12 @@ viewport's aspect ratio.
   @lr-take-over=${(e) => setController(e.detail.controller)} @lr-stop=${() => stopSession()}
 ></lr-browser-frame>
 ```
+
+**Additional API surface:**
+
+- `--lr-browser-frame-controller-background` — Controller badge background. Default: `var(--lr-color-brand-quiet)`.
+- `--lr-browser-frame-controller-color` — Controller badge text color. Default: `var(--lr-color-brand)`.
+- `--lr-browser-frame-ping-click-color` — Click-ping border color. Default: `var(--lr-color-brand)`.
+- `--lr-browser-frame-ping-type-color` — Type-ping border color. Default: `var(--lr-color-success)`.
+- `--lr-browser-frame-ping-scroll-color` — Scroll-ping border color. Default: `var(--lr-color-warning)`.
+- `--lr-browser-frame-ping-move-color` — Move-ping border color. Default: `var(--lr-color-text-quiet)`.

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

@@ -5,7 +5,8 @@
 - **Import** `import '@aceshooting/lyra-ui/components/charts/chart/bubble-chart.js';` (registers the tag; side-effect import)
 - **Class** `LyraBubbleChart`, also available unregistered from `@aceshooting/lyra-ui/components/charts/chart/bubble-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
 - **Documented with** `lr-line-chart`, `lr-bar-chart`, `lr-pie-chart`, `lr-doughnut-chart`, `lr-radar-chart`, `lr-polar-area-chart`, `lr-scatter-chart` (same section below)
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
@@ -26,7 +27,8 @@ 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`
+(`y2-label`), `beginAtZero` (`begin-at-zero`), `horizontal`, `stacked`, `dataLabels`
+(`data-labels`), `stackTotals` (`stack-totals`), `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.
@@ -47,7 +49,7 @@ dependency fails to load — see `llms/components/lr-chart.md`).
 `--lr-chart-tooltip-text`.
 
 **Optional peer deps:** same as `lr-chart` — `chart.js`, plus `chartjs-plugin-zoom` only once
-`zoom` is set.
+`zoom` is set, and `chartjs-plugin-datalabels` only once `data-labels`/`stack-totals` is set.
 
 ```html
 <lr-bar-chart legend></lr-bar-chart>

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

@@ -6,6 +6,7 @@
 - **Class** `LyraButtonGroup`, also available unregistered from `@aceshooting/lyra-ui/components/layout/button-group/button-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-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
@@ -37,19 +58,24 @@ shadow-internal native button doesn't participate in an ancestor form's submissi
 - `loading: boolean = false` (reflected) — shows an internal spinner and disables the button without
   clearing `disabled`
 - `disabled: boolean = false` (reflected)
+- `accessibleLabel: string | null = null` (attribute `aria-label`) — accessible name forwarded
+  reactively to the internal native button or anchor; changing or removing the attribute after
+  mount updates the actual focused control
 
 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 +103,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
@@ -110,9 +139,14 @@ box no matter what tier or override is in play.
 ```
 
 **Known gotchas:**
-- A host `aria-label` is forwarded to the internal button as a literal string (for an icon-only
-  button); an external `aria-labelledby`/`aria-describedby` idref is not copied across the shadow
-  boundary.
+- `accessibleLabel`/a host `aria-label` is forwarded reactively to the internal button or anchor as
+  a literal string (for an icon-only button); an external `aria-labelledby`/`aria-describedby`
+  idref is not copied across the shadow boundary.
+- Host `aria-haspopup` and `aria-expanded` values are forwarded to the internal semantic control.
+  For host `aria-controls`, targets in the host's own root are resolved through the reflected
+  element-reference API so a popup relationship survives the component's shadow boundary; browsers
+  without that API retain the forwarded string attribute as a best-effort fallback. This is what
+  lets either button serve as an `lr-menu` trigger.
 - Is form-associated (`static formAssociated = true` + `attachInternals()`), so it participates in
   an ancestor `<form>.elements` the same way `wa-button` does — a sibling text field's own
   Enter-to-submit lookup (which scans `form.elements` for a `type === 'submit'` control) finds it.

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** 7 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**
@@ -85,4 +91,9 @@ the `footer` slot, hidden entirely when empty).
   `<lr-button>` retargets to the host, but its composed path still contains the internal native
   `<button>`.
 
+**Additional API surface:**
+
+- `accessibleLabel` — Host `aria-label` forwarded to the native no-href activation button. Type: `string | null`.
+- `part="activation-button"` — The native whole-card action, rendered while `interactive` without `href`. It is a sibling of slotted controls, so actionable descendants are never nested inside another actionable role.
+
 ---

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,39 @@ 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()` resets 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. 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. `exportData('csv' | 'png')` returns a
+spreadsheet-safe CSV snapshot or the current PNG data URL when Chart.js is loaded.
+
+The instance method `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. Each internal
+token resolves through the matching application input (`--lr-theme-color-chart-1..8`), so theme
+overrides are included.
+
+The module also exports `seriesPalette(scope?: Element | null): string[]`, which can run before a
+chart exists. Omit `scope` to read `document.documentElement`, pass an element to resolve its theme
+scope, or pass `null` to request the light-mode fallback directly. When a scope has no component
+token layer yet, the helper reads the `--lr-theme-color-chart-N` inputs directly. Both forms return
+a fresh eight-color array each call (safe to mutate) and let chart-adjacent UI, KPI tiles, or the
+`Series` array itself come from one source of truth.
+
+```ts
+import { seriesPalette } from '@aceshooting/lyra-ui/components/charts/chart/chart.js';
+
+const colors = seriesPalette();
+const series = [
+  { label: 'Revenue', data: [12, 19], color: colors[0] },
+  { label: 'Costs', data: [7, 11], color: colors[1] },
+];
+```
 
 **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 +159,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, 19 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.
@@ -147,7 +153,8 @@ between several values across a single element's lifetime.
 - mounting a message with `status="failed"` (or any other non-`"sent"` status) already set does
   **not** announce anything — only a genuine *later* transition (`changed.get('status') !==
   undefined`, i.e. not the very first update) triggers the live-region announcement.
-- `lr-retry` fires with no detail payload at all (`undefined`), not e.g. `{ status: 'failed' }`.
+- `lr-retry` carries `{ messageId?: string }`; the field is the component's `messageId` when set,
+  and is omitted otherwise.
 - the header/footer/avatar/badges/attachments/actions wrappers are shown/hidden via the `hidden`
   attribute, not conditional templating. Whether each slot currently has content is checked once via
   a light-DOM children scan on the very first update (`willUpdate`, gated on `!this.hasUpdated`) and
@@ -158,4 +165,18 @@ between several values across a single element's lifetime.
 - `role` intentionally reflects to `data-role`; CSS or selectors that key off role must target
   `[data-role="user"]` etc., not `[role="user"]`.
 
+**Additional API surface:**
+
+- `--lr-chat-message-system-color` — System-message text color. Default: `var(--lr-color-text-quiet)`.
+- `--lr-chat-message-streaming-border-color` — Streaming bubble border. Default: `var(--lr-color-brand)`.
+- `--lr-chat-message-failed-border-color` — Failed bubble border. Default: `var(--lr-color-danger)`.
+- `--lr-chat-message-failed-bg` — Failed bubble fill. Default: `var(--lr-color-danger-quiet)`.
+- `--lr-chat-message-footer-color` — Default footer text. Default: `var(--lr-color-text-quiet)`.
+- `--lr-chat-message-user-footer-color` — User-message footer text. Default: `var(--lr-color-text)`.
+- `--lr-chat-message-failed-footer-color` — Failed-message footer text. Default: `var(--lr-color-danger)`.
+- `--lr-chat-message-indicator-color` — Default status indicator. Default: `var(--lr-color-text-quiet)`.
+- `--lr-chat-message-streaming-indicator-color` — Streaming indicator. Default: `var(--lr-color-brand)`.
+- `--lr-chat-message-failed-indicator-color` — Failed indicator. Default: `var(--lr-color-danger)`.
+- `--lr-chat-message-failed-status-color` — Failed status text. Default: `var(--lr-color-danger)`.
+
 ---

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`
 
 ---
@@ -17,16 +18,21 @@ selected value is submitted under `name` and `required` requires at least one se
 
 **Properties:** `label`, `hint`, `errorText`, `value`, `name`, `required`, `disabled`, and
 `accessibleLabel` (`aria-label`). **Slots:** default checkboxes, `label`, `hint`, `error`.
-**Events:** `input`, `change`, and `lr-change` with `{ value: string[] }`.
+**Events:** a user toggle emits exactly one group-owned `input`, then `change`, then `lr-change`;
+all three carry `{ value: string[] }`. The owned child's corresponding events are consumed at the
+group boundary, so an ancestor does not receive a second, differently shaped sequence.
+Programmatic child/property synchronization is silent.
 **CSS parts:** `form-control`, `form-control-label`, `options`, `hint`, `error`.
 
 **`value` is a read-out of child state, not an input.** The children are the single source of
 truth. An internal sync recomputes `value` from them and reassigns it on every child toggle,
-`slotchange`, `name`/`required` change, blur, and `form.reset()` — so a host assignment is
-silently overwritten by the next of those. `connectedCallback()` runs that sync **before the first
-render**, which means even a constructor-time or template-time `.value=${…}` binding is discarded
-before anything can observe it. Assigning `value` logs a `console.warn` naming the property (once
-per group instance).
+programmatic child `checked`/`value`/`disabled` update, `slotchange`, `name`/`required` change,
+blur, and `form.reset()` — so a host assignment is silently overwritten by the next of those.
+Only a checkbox whose nearest `lr-checkbox-group` ancestor is this group contributes; a nested
+group owns its own descendants and form entries. `connectedCallback()` runs that sync **before the
+first render**, which means even a constructor-time or template-time `.value=${…}` binding is
+discarded before anything can observe it. Assigning `value` logs a `console.warn` naming the
+property (once per group instance).
 
 - **To preselect**, set `checked` on the children: `<lr-checkbox value="a" checked>`.
 - **To read the selection**, use this property or the `lr-change` event detail.

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`
 
 ---
@@ -31,12 +32,16 @@ visual box/checkmark. Structurally the same idea as `<lr-switch>` (form-associat
 `lr-change` alias (`detail: { checked: boolean }`). Programmatic `.checked` assignments are
 silent. Internal `focus`/`blur` are re-dispatched as bubbling, composed host events.
 
-**Methods:** `focus(options?)` and `blur()` forward to the internal checkbox control.
+**Methods:** `focus(options?)`, `blur()`, and `click()` forward to the internal checkbox control.
 
 **Slots:** default — label text, rendered next to the box. Clicking it toggles the checkbox, the
 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`
 
@@ -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