@aceshooting/lyra-ui 6.1.0 → 6.2.0

package/llms-full.txt

@@ -40,8 +40,8 @@ family and entry point.
 - **Charts** — 12 tags in `components/charts/`
 - **Document & file viewers** — 22 tags in `components/viewers/`
 - **Conversation & chat UI** — 28 tags in `components/conversation/`
-- **Agent tooling, tool calls & evaluation** — 29 tags in `components/agent-tools/`
-- **Retrieval, knowledge graph & grounding** — 24 tags in `components/retrieval/`
+- **Agent tooling, tool calls & evaluation** — 31 tags in `components/agent-tools/`
+- **Retrieval, knowledge graph & grounding** — 27 tags in `components/retrieval/`
 - **Reference tables** — design tokens (`llms/tokens.md`), optional peers (`llms/peers.md`), `wa-*`/`sl-*` migration (`llms/migration.md`)
 
 ---
@@ -240,6 +240,94 @@ dark palette — that fallback applies only where no real `--lr-theme-*` value i
 The token layer also sets `:host([hidden]) { display: none !important; }` and an inherited
 `box-sizing: border-box` reset.
 
+### Theme mode/accent runtime (`@aceshooting/lyra-ui/theme.js`)
+
+Flipping the mode class/attribute above is something every app ends up hand-rolling — persist a
+choice, apply it on load, avoid the flash of wrong theme before the app boots. `theme.js` is that
+runtime, published as its own subpath: **zero dependencies, no Lit, no component imports, and no
+side effects on import**, so an app can persist and apply a theme without pulling the component
+graph into its first-paint bundle.
+
+```ts
+import { setLyraTheme, getLyraTheme } from '@aceshooting/lyra-ui/theme.js';
+
+setLyraTheme({ mode: 'dark' });                  // unspecified fields keep their current value
+setLyraTheme({ accent: '#7c3aed' });             // mode stays 'dark'
+getLyraTheme();                                  // → { mode: 'dark', accent: '#7c3aed' }
+setLyraTheme({ mode: 'auto', accent: null });    // clears the override and the accent
+```
+
+- **`setLyraTheme({ mode?, accent? })`** persists to `localStorage['lyra-theme']`, applies to
+  `document.documentElement`, and dispatches `lr-theme-change` on `window` with
+  `detail: { mode, accent }`. Fields you omit keep their current value; pass `null` to clear the
+  accent. It **never throws** — when `localStorage` is unavailable (private browsing, quota, a
+  sandboxed iframe) it degrades to apply-without-persist, and the "fields you omit keep their
+  current value" rule still holds across calls in that state: the merge falls back to the last
+  theme applied in this session rather than to the default.
+- **`getLyraTheme()`** returns `{ mode, accent }`, defaulting to `{ mode: 'auto', accent: null }`
+  when nothing is stored or the stored value is malformed. Storage is re-read on every call — no
+  in-memory cache — so a value written by another tab or a previous session is picked up cold.
+  Where storage is unreadable or unwritable it reports the theme last applied, so the return value
+  always describes what the document is actually showing and a toggle UI bound to it stays in sync.
+- **`mode`** is `'light' | 'dark' | 'auto'`. `'light'`/`'dark'` set **both `data-lr-theme`** (the
+  attribute `theme.css` actually keys its palette blocks on) **and `data-theme`** (the generic
+  attribute canvas-rendered components watch, so `lr-chart`/`lr-heatmap`/`lr-qr-code` repaint on
+  the switch rather than keeping stale colors — see `llms/components/lr-chart.md`). `'auto'`
+  removes both, which means **no override — not "follow the OS"**:
+  - **With `theme.css` imported** (the setup this section is nested under), its `:root` block sets
+    the full light palette unconditionally and that file ships no `prefers-color-scheme` block, so
+    `'auto'` renders **light** whatever the OS is set to.
+  - **Without `theme.css`**, no real `--lr-theme-*` value is set, so the token layer's
+    `prefers-color-scheme: dark` fallback described above does apply and bare components follow
+    the OS.
+
+  To follow the OS *alongside* `theme.css`, resolve the preference yourself and pass a concrete
+  mode — `setLyraTheme` deliberately does no `matchMedia` work of its own:
+  ```ts
+  const os = matchMedia('(prefers-color-scheme: dark)');
+  const sync = () => setLyraTheme({ mode: os.matches ? 'dark' : 'light' });
+  sync();
+  os.addEventListener('change', sync);
+  ```
+- **`accent`** is written to `--lr-theme-accent` as an inline custom property on the root element.
+  This is a **hook for your CSS, not a token the library reads** — no lyra-ui component consumes
+  `--lr-theme-accent`. Point the real inputs at it to make it retint anything, **writing one rule
+  per mode**:
+  ```css
+  :root { --lr-theme-color-brand-fill-loud: var(--lr-theme-accent, #0969da); }
+  .lr-dark,
+  [data-lr-theme='dark'] { --lr-theme-color-brand-fill-loud: var(--lr-theme-accent, #4ea0f0); }
+  ```
+  **Each arm's fallback must carry that mode's own value.** A single `:root` rule flattens both
+  modes to one color whenever the accent is unset (`accent: null`, the default): `:root` and
+  `[data-lr-theme='dark']` have equal specificity and both match `<html>` — the element
+  `setLyraTheme` writes `data-lr-theme` onto — so a consumer stylesheet loaded after `theme.css`
+  wins the tie on source order and pins the light-mode blue in dark mode. Copy each fallback from
+  the matching palette block in `theme.css` (`#0969da` light / `#4ea0f0` dark here).
+
+  Because that is a `--lr-theme-*` input, it reaches every nested shadow root — see "Where an
+  override actually reaches" above for why setting a `--lr-*` token instead would not.
+
+**No-flash bootstrap.** `lyraThemeBootstrap` is a self-contained IIFE **string** (not a function),
+meant to be inlined into a `<script>` in `<head>` **before any stylesheet**, so the persisted theme
+is on the root element before first paint. It is a string precisely so this can happen in an
+unbundled `<script>` context without shipping or parsing the module:
+
+```html
+<head>
+  <script>/* server-inlines lyraThemeBootstrap here */</script>
+  <link rel="stylesheet" href="/theme.css" />
+</head>
+```
+
+It reads the same storage key, applies the same two attributes and `--lr-theme-accent`, and
+swallows any error — malformed storage or a blocked `localStorage` leaves the document untouched
+rather than throwing before your app loads.
+
+**This runtime does no color math.** It stores and applies whatever accent string you give it; it
+does not validate the value, compute a palette from it, or check contrast against any surface.
+Verifying that an accent meets WCAG contrast against the light *and* dark palettes is yours.
+
 ## Localization: `locale`, `strings`, and the locale runtime
 
 Every built-in string — button labels, accessible names, descriptions, validation messages, status
@@ -545,14 +633,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
@@ -573,11 +668,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
@@ -594,8 +694,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
@@ -605,6 +705,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
@@ -634,6 +760,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 —
@@ -695,7 +829,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
@@ -734,7 +868,8 @@ input: click/Enter/Space/ArrowDown opens it, and there's no typing-to-filter. Op
 `<lr-option value>` children — the same element `<lr-combobox>` uses — reconciled the same way
 combobox does, and the popup reuses `internal/positioner.ts` for placement.
 Session-history/autofill restoration assigns the stored string through the same synchronous
-value/form/validity path as a programmatic value write and does not emit `input` or `change`.
+value/form/validity path as a programmatic value write and does not emit `input`, `change`, or
+`lr-change`.
 
 Single-select only, with no `filter`/`source`/`with-clear`/`max-options-visible`/`empty-text`/
 `max-render`/`multiple` surface — reach for `<lr-combobox>` instead whenever any of those apply.
@@ -767,8 +902,10 @@ exactly like the multi-option case, until the trigger is actually activated.
 - `value: string` — a getter/setter; always a single string (no `multiple` mode)
 
 **Events:** `change` (native-style — selection changed), `input` (fired alongside `change` on every
-selection change — a native `<select>` doesn't meaningfully distinguish the two either),
-`lr-show`, `lr-hide`
+selection change — a native `<select>` doesn't meaningfully distinguish the two either), and
+`lr-change` (a prefixed compatibility alias fired after both, mirroring `<lr-checkbox>`'s
+`lr-change`). All three carry `detail: { value: string }` (the new selection) and fire only on a
+real change, never on a programmatic `value` write. Plus `lr-show`, `lr-hide`.
 
 **Slots:** default (`<lr-option>` children), `label`, `hint`, `error` (overrides the `errorText`
 attribute when provided)
@@ -820,6 +957,15 @@ ancestor is never shadowed — retheme just this row state without hijacking the
 `--lr-color-brand-quiet` token every other component's own hover/active state also reads. Same
 knob `lr-combobox`'s own `--lr-combobox-option-active-bg` provides.
 
+The currently-**selected** row (`[part='option'][aria-selected='true']`) has its own matching set:
+`--lr-select-option-selected-bg` (default `transparent`), `--lr-select-option-selected-border` and
+`--lr-select-option-selected-color` (both default `var(--lr-color-brand)`), and
+`--lr-select-option-selected-font-weight` (default `var(--lr-font-weight-semibold)`). 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. Note the shadow-parts
+spec forbids an attribute selector after `::part()` — `::part(option)[aria-selected='true']` is
+invalid CSS and never matches — which is exactly why these tokens exist.
+
 **Optional peer deps:** none.
 
 ```html
@@ -1105,10 +1251,29 @@ submission/validation/reset via `name`/`value`/`disabled`/`required`/`checkValid
 | `autocomplete` | `autocomplete` | `string` | `''` | Forwarded to the native `<textarea>`; empty omits the attribute. |
 | `inputMode` | `inputmode` | `string` | `''` | Virtual-keyboard input hint forwarded to the native `<textarea>`. |
 | `enterKeyHint` | `enterkeyhint` | `string` | `''` | Virtual-keyboard Enter-key hint forwarded to the native `<textarea>`. |
+| `minlength` | `minlength` | `number \| undefined` | `undefined` | Minimum text length; forwarded to the native `<textarea>` and reported as `validity.tooShort`. |
+| `maxlength` | `maxlength` | `number \| undefined` | `undefined` | Maximum text length; forwarded to the native `<textarea>` (which also stops typing past it) and reported as `validity.tooLong`. |
 | `name` | `name` | `string` | `''` | Form field name. |
 | `disabled` | `disabled` | `boolean` | `false` | Disables the control. |
 | `required` | `required` | `boolean` | `false` | Participates in native constraint validation. |
 
+### Constraint validation
+
+`validity` reports `valueMissing` (from `required`), `tooShort` (from `minlength`), and `tooLong`
+(from `maxlength`) — the complete set a native `<textarea>` can produce. Leaving `minlength` and
+`maxlength` unset constrains nothing, exactly as before they existed.
+
+Two behaviors are worth knowing, both inherited from the platform and both shared with `lr-input`:
+
+- **An empty value is never `tooShort`.** Native `minlength` only applies to a non-empty value, so
+  an optional field left blank stays valid; `required` is what rejects empty.
+- **A script-assigned value is validated too.** The native `tooShort`/`tooLong` flags are raised
+  only for a value the *user* edited, so the component recomputes both from its own `value` and
+  ORs them in — `el.value = <over-length>` reports `tooLong` rather than silently submitting.
+  Lengths count UTF-16 code units, matching the native control (one emoji counts as two).
+  `validationMessage` is the browser's own localized message when the native control flagged the
+  value, and the localized `valueInvalid` string when only the script-value check did.
+
 The visible label, hint, and error live in the same shadow tree as the native control, so their
 generated ids safely drive the native `<label>`/`aria-describedby` relationships. Name precedence
 is `accessibleLabel`/host `aria-label`, visible `label`, `placeholder`, then the localized
@@ -1181,7 +1346,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
@@ -1206,15 +1391,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
@@ -1242,6 +1429,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
@@ -1286,9 +1476,8 @@ box no matter what tier or override is in play.
 
 ## `lr-icon-button`
 
-An accessible icon-only action button — a native `<button>` wrapping an `lr-icon`. Not
-form-associated: it is an action trigger, so `type="submit"`/`"reset"` work through the ancestor
-form the way a native button does, but the element itself contributes no form value.
+An accessible icon-only action button — a form-associated custom element with a native `<button>`
+inside. Its `type="submit"`/`"reset"` behavior is forwarded to the ancestor form by the component.
 
 **Properties:**
 - `icon: string = ''` — an `lr-icon` glyph name (see `llms/components/lr-icon.md`)
@@ -1339,7 +1528,13 @@ that several other components size their icon-only controls against), so overrid
 above 24px — see `llms/shared.md`. `--lr-icon-button-radius` (default `--lr-radius`) is the
 `[part='button']` corner radius, retunable without a `::part(button)` rule — the same
 `--lr-button-radius` pattern; `lr-icon-button` has no `size` tiers, so there is no per-tier gap
-counterpart to it.
+counterpart to it. `--lr-icon-button-background` (default `transparent`) tints the
+`[part='button']` background, `--lr-icon-button-background-hover` (default `--lr-color-surface`)
+its hover-state background, and `--lr-icon-button-color` (default `inherit`) its icon/text color —
+the same per-component indirection `lr-button`'s `--lr-button-fill`/`--lr-button-on-fill` provide,
+letting you tint a single button without a `::part(button)` rule. Left unset, each falls back to
+today's value, so rendering is unchanged. There is deliberately no border-color token:
+`[part='button']` sets `border: 0`, so a border color could never render.
 
 ## `lr-input`
 
@@ -1373,6 +1568,13 @@ form-associated via the same `FormAssociated` mixin as `lr-textarea`. Ships the
   non-numeric bound only survives a direct property assignment; the declared type also admits a
   string so a subclass can narrow the attribute parsing to its own native type's literal form —
   `lr-time-input` does exactly that. Inert for the other types
+- `minlength?: number` / `maxlength?: number` (attributes `minlength`/`maxlength`) — text-length
+  bounds forwarded to the native input and reported as `validity.tooShort`/`validity.tooLong`.
+  Apply to the text-bearing types (`text`, `search`, `email`, `password`); the platform ignores
+  both on `type="number"`/`type="time"`, and so does this component
+- `pattern?: string` (attribute `pattern`) — a regular expression the value must match in full,
+  forwarded to the native input and reported as `validity.patternMismatch`. Anchored to the whole
+  value by the platform, so no `^`/`$` is needed; an empty value never violates it
 - `passwordVisible: boolean = false` (attribute `password-visible` — `type="password"` only)
 - `name`/`disabled`/`required` (from `FormAssociated`)
 
@@ -1447,7 +1649,19 @@ Several controls expose the same pair: a per-`size` `*-min-height` **floor**, an
 **Known gotchas:**
 - `type="email"`/`type="number"` delegate constraint validation to the internal native `<input>`'s
   own browser-computed `validity` (format/range/step), bridged into this element's own
-  `ElementInternals` — not a second hand-rolled regex check.
+  `ElementInternals` — not a second hand-rolled regex check. The same bridge carries
+  `minlength`/`maxlength`/`pattern`, so `validity` reports the full native set: `valueMissing`,
+  `typeMismatch`, `rangeUnderflow`, `rangeOverflow`, `stepMismatch`, `tooShort`, `tooLong`,
+  `patternMismatch`, and `badInput`.
+- **`tooShort`/`tooLong` also fire for a value assigned from script.** The native flags are raised
+  only for a value the *user* edited, so the component recomputes both from its own `value` and ORs
+  them in; `el.value = <over-length>` reports `tooLong` rather than silently submitting. Lengths
+  count UTF-16 code units, matching the native control (one emoji counts as two). `patternMismatch`
+  needs no such handling — the platform applies `pattern` to script-assigned values already.
+  `validationMessage` is the browser's own localized message when the native input flagged the
+  value, and the localized `valueInvalid` string when only the script-value check did.
+- An empty value is never `tooShort` and never a `patternMismatch` — both native constraints skip
+  the empty string, and `required` is what rejects it.
 - `type="password"` always renders the `password-toggle` button; there is no separate opt-out.
 
 ## `lr-number-input`
@@ -1459,8 +1673,8 @@ A migration-friendly numeric alias of `lr-input` — a subclass whose constructo
 **Properties:** `size` (`2xs`…`xl`), `placeholder`, `readonly`, `label`, `hint`, `errorText`
 (`error-text`), `accessibleLabel` (`aria-label`), `autocomplete`, `spellcheck`, `autocapitalize`,
 `autoCorrect` (`autocorrect`), `inputMode` (`inputmode`), `enterKeyHint` (`enterkeyhint`), and
-`min`/`max`/`step` (the native numeric constraint validation). `clearable` and `passwordVisible`
-(`password-visible`) are inherited but inert — see gotchas.
+`min`/`max`/`step` (the native numeric constraint validation). `clearable`, `passwordVisible`
+(`password-visible`), and `minlength`/`maxlength`/`pattern` are inherited but inert — see gotchas.
 
 **Events:** `input`/`change` (native-style, composed), `lr-input`/`lr-change`
 (`detail: { value }`), `focus`/`blur` (re-dispatched bubbling + composed from the internal native
@@ -1482,7 +1696,8 @@ vary by `size` at all).
 **Known gotchas:**
 - `clearable`/`clear-button`/`lr-clear` are inert: the clear action only renders for
   `type="text"`/`"search"`. `password-visible`/`password-toggle` are likewise inert, since the
-  toggle only renders for `type="password"`.
+  toggle only renders for `type="password"`. `minlength`/`maxlength`/`pattern` are inert too — the
+  platform ignores all three on `type="number"`; use `min`/`max`/`step` instead.
 - `type` is re-forced to `number` on every connect, but a later `el.type = 'text'` on a connected
   element is not reverted — use `lr-input` when the type has to change.
 
@@ -1495,8 +1710,9 @@ re-typed `min`/`max` pair (below); every other property, event, slot and part is
 **Properties:** `size` (`2xs`…`xl`), `placeholder`, `readonly`, `label`, `hint`, `errorText`
 (`error-text`), `accessibleLabel` (`aria-label`), `autocomplete`, `spellcheck`, `autocapitalize`,
 `autoCorrect` (`autocorrect`), `inputMode` (`inputmode`), and `enterKeyHint` (`enterkeyhint`).
-`clearable` and `passwordVisible` (`password-visible`) are inherited but inert, exactly as on
-`lr-number-input`.
+`clearable`, `passwordVisible` (`password-visible`), and `minlength`/`maxlength`/`pattern` are
+inherited but inert, exactly as on `lr-number-input` — the platform ignores all three length/pattern
+constraints on `type="time"` as well.
 
 `step` is forwarded verbatim to the native time input, where it means seconds (`step="1"` reveals
 the seconds field, `'any'` disables step validation).
@@ -1838,16 +2054,18 @@ named colors, the shape apps otherwise hand-roll as a row of round accent-color
 
 **Properties:**
 - `options: SwatchOption[] = []` (attribute: false) — `SwatchOption { value: string; color: string;
-  label: string; icon?: unknown }`; `color` is any CSS color string used as the swatch fill, `label`
-  is each swatch's accessible name and `title`. `icon` is an optional custom shape (e.g. a gem
-  glyph) rendered *instead of* the plain filled circle; the swatch sets `color: <option color>` so a
-  `currentColor`-based SVG picks the option's color up automatically, matching
-  `<lr-segmented>`'s `SegmentedItem.icon`.
+  label: string; icon?: unknown; gemstone?: GemstoneKey }`; `color` is any CSS color string used as
+  the swatch fill, `label` is each swatch's accessible name and `title`. `icon` is an optional
+  custom shape rendered *instead of* the plain filled circle; `gemstone` selects the canonical
+  faceted glyph when `mode="gemstone"`. An explicit `icon` wins over `gemstone`.
 - `value: string | null = null` — the currently selected option's `value` (controlled); `null`
   leaves nothing selected while keeping the first swatch tabbable.
 - `size: '2xs' | 'xs' | 's' | 'm' | 'l' | 'xl' = 'm'` (reflected — scales the swatch hit-area and
   fill diameter proportionally, hit-area floored at 24px; not pixel-matched to `lr-input`'s
   row-height scale)
+- `mode: 'swatch' | 'gemstone' = 'swatch'` (reflected) — `swatch` preserves the plain-circle
+  default. `gemstone` renders the shared glyph for options carrying a `gemstone` key and enables
+  the selected glow/shine defaults.
 - `label: string = ''` — accessible name copied to the internal `role="radiogroup"`; when empty, a
   host-level `aria-label` is used as a fallback.
 
@@ -1876,7 +2094,9 @@ for a looping brighten-and-settle pulse on the selected swatch. It drives a sepa
 works identically for a fill and an icon; disabled outright under `prefers-reduced-motion: reduce`,
 which also drops the hover/selection scale transition), `--lr-swatch-picker-hit-size` (hit-area
 size, swapped per `size` tier), `--lr-swatch-picker-fill-size` (visible fill/icon diameter, swapped
-per `size` tier); plus shared tokens — `--lr-color-border`/`-brand`, `--lr-space-xs`,
+per `size` tier), `--lr-swatch-picker-gemstone-selected-blur` (default `--lr-size-0-5rem` in
+gemstone mode), `--lr-swatch-picker-gemstone-shine-duration` (default `1.8s` in gemstone mode);
+plus shared tokens — `--lr-color-border`/`-brand`, `--lr-space-xs`,
 `--lr-border-width-thin`/`-thick`, `--lr-radius`, `--lr-transition-fast`, `--lr-focus-ring-*`,
 and the per-tier `--lr-size-*` tokens.
 
@@ -1896,6 +2116,24 @@ and the per-tier `--lr-size-*` tokens.
 </script>
 ```
 
+For the shared gemstone accent mode, import the side-effect-free palette/glyph helper. The
+consumer still owns localized labels, display order, and the initial value:
+
+```ts
+import '@aceshooting/lyra-ui/components/forms/swatch-picker/swatch-picker.js';
+import { GEMSTONES } from '@aceshooting/lyra-ui/theme/gemstones.js';
+
+const order = ['emerald', 'ruby', 'sapphire', 'hematite'] as const;
+picker.mode = 'gemstone';
+picker.options = order.map((key) => ({
+  value: key,
+  color: GEMSTONES[key].fill,
+  label: translateGemstone(key),
+  gemstone: key,
+}));
+picker.value = 'ruby';
+```
+
 **Known gotchas:**
 - arrow-key navigation cycles (past the last swatch wraps to the first, and vice versa) rather than
   clamping, and self-selects on move — arrow-navigating to a swatch immediately updates `value` and
@@ -1940,6 +2178,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)
@@ -2871,6 +3113,9 @@ own "consumer computes/renders" contract rather than assuming addition.
   button's label once they've been revealed)
 - `showAllColumns: boolean = false` (attribute `show-all-columns`, reflected) — forces responsive
   priority columns visible and is updated by the built-in reveal button
+- `storageKey?: string` (attribute `storage-key`) — when set, persists `showAllColumns` to
+  `localStorage` (namespaced as `lr-table:${storageKey}`) and restores it on the next mount. Unset
+  (the default) touches storage not at all. Mirrors `lr-app-rail`'s identical `storage-key` pattern
 - `heatTintScale?: { min?: number; max?: number }` (attribute: false) — overrides the auto-derived
   heat-tint domain (min/max of every `heatValue` result across every currently-rendered row —
   post-sort, pre-pagination, the same rows `footer(rows)` already sees). Unset (the default) computes
@@ -2939,6 +3184,11 @@ element *or on any ancestor* and still reach the rule that reads it. It exists b
 forbids an attribute selector after `::part()` — `::part(row)[aria-selected='true']` is invalid CSS —
 so the only prior lever for restyling the selected row was overriding the library-wide
 `--lr-color-brand-quiet` token, which repaints everything else reading it.
+`--lr-table-header-sorted-bg` (default `transparent`) and `--lr-table-header-sorted-color` (default
+`inherit`) restyle the **currently-sorted** column's header cell (`[aria-sort]` other than `none`).
+Same shape and rationale as `--lr-table-row-selected-bg`: inline `var()` fallbacks, not on `:host`,
+because `::part(header-cell)[aria-sort]` is invalid CSS. The `sort-icon` part styles only the
+chevron; these tokens style the header cell itself.
 `--lr-table-sticky-offset` (default `0`) is measured and written inline per column by the component
 so multiple `sticky` columns stack instead of overlapping; it is a read-out, not a knob you set.
 `--lr-table-heat-t` is likewise component-written (each `[data-heat]` cell's position on the ramp).
@@ -2964,11 +3214,16 @@ so multiple `sticky` columns stack instead of overlapping; it is a read-out, not
 - only single-row selection is modeled (`selectedKey: string | number | null`);
   there's no bulk-select/checkbox-column API — you must hand-roll a checkbox column entirely inside
   a `cell()` callback if you need multi-select.
-- no `caption`/`aria-label` *property* exists, but a plain `aria-label` HTML attribute set on the
-  host **is** forwarded into the shadow-DOM `<table role="grid">` (read via
-  `this.getAttribute('aria-label')` at render time — a plain global-attribute read, not a reactive
-  Lit `@property`): `<lr-table aria-label="Scores">` gives the grid an accessible name; omit it and
-  the shadow table simply has none.
+- `accessibleLabel: string = ''` (attribute `accessible-label`) — a typed accessible name for the
+  `<table role="grid">`. A plain `aria-label` HTML attribute on the host is also forwarded (read via
+  `this.getAttribute('aria-label')` at render time) and serves as a fallback when `accessibleLabel`
+  is unset. Consumer-supplied text, so neither is run through `this.localize()`.
+- `caption: string = ''` — an optional visible `<caption>` (exposed as the `caption` CSS part). When
+  no `accessibleLabel`/host `aria-label` is present the caption also names the grid via
+  `aria-labelledby`.
+- A grid with **none** of `accessibleLabel`, host `aria-label`, or `caption` logs a one-time
+  `console.warn` on first render (dev signal) — an unnamed grid is an accessibility defect that
+  otherwise renders silently.
 - Full roving-tabindex grid keyboard pattern (one `tabindex="0"` stop among header cells, one among
   body rows) — Left/Right/Home/End move within the header row, Up/Down/Home/End move within the
   body, Down from the header enters the body's roving stop and Up from the body's first row returns
@@ -3179,6 +3434,12 @@ visually-hidden `[part="live-region"]` (`role="status" aria-live="polite"`) anno
   90° for denser packing
 - `palette?: string[]` (attribute: false) — custom categorical colors, cycled by word index (or by
   `group`); defaults to the `--lr-word-cloud-color-1..8` tokens
+- `legend: WordCloudLegendItem[] = []` (attribute: false) — optional named `{ label, color }`
+  entries for explaining explicit `words[].color`/group color overrides; when omitted, the
+  component derives entries from grouped and explicitly colored words
+- `showLegend: boolean = false` (attribute `show-legend`, reflected) — renders the supplied or
+  derived legend below the cloud; the color key is an accessible list and does not change word
+  activation or palette selection
 
 **Methods:** `refreshTheme(): void` — forces a relayout so the `--lr-font` custom property is
 re-read from computed style (font-family affects the canvas text measurement layout depends on);
@@ -3192,8 +3453,8 @@ the currently-focused word — a no-op if nothing is focused yet)
 
 **CSS parts:** `base`, `svg`, `word` (each `<text>`), `focus-ring` (the rect around the roving-focus
 cursor's word), `live-region` (visually-hidden `role="status" aria-live="polite"` announcement text),
-`empty` (the no-data placeholder — hardcoded `"No data"` text, no property to customize it, unlike
-`lr-empty`/`lr-table`)
+`legend`/`legend-item`/`legend-swatch`/`legend-label` (the optional static color key), and `empty`
+(the no-data placeholder)
 
 **Themeable custom properties:** `--lr-word-cloud-color-1`, `--lr-word-cloud-color-2`,
 `--lr-word-cloud-color-3`, `--lr-word-cloud-color-4`, `--lr-word-cloud-color-5`,
@@ -4321,9 +4582,16 @@ auto-inserted between each adjacent pair.
 **Properties:**
 - `sizes: number[] = []` (attribute: false — percentages per panel, auto-computed equally if
   omitted/mismatched)
-- `defaultSizes: number[] = []` (attribute: false) — initialization-only fallback: a valid restored
-  `storageKey` layout wins first; otherwise a valid `defaultSizes` wins over equal distribution.
-  Later reassignment never overwrites live drag/persisted state — set it once, at mount.
+- `defaultSizes: (number | string)[] = []` (attribute: false) — initialization-only fallback: a
+  valid restored `storageKey` layout wins first; otherwise a valid `defaultSizes` wins over equal
+  distribution. Later reassignment never overwrites live drag/persisted state — set it once, at
+  mount. Each entry is either a plain **number** (percent-of-container, validated unchanged: a
+  pure-number array that does not sum to ~100, e.g. `[30, 60]`, is still rejected and falls through
+  to the equal split) or a CSS **length string** (`'200px'`, `'20%'`, `'3rem'`). When at least one
+  entry is a length string, every entry is resolved against the measured container (numbers as
+  percent-of-container, `%` as-is, `px`/`rem`/`em` via the shared length resolver) and then
+  normalized to percentages before the same validation applies — so `['200px', '300px']` on a 500px
+  container initializes to `[40, 60]`.
 - `min: number = 10` (min % per panel)
 - `orientation: 'horizontal'|'vertical' = 'horizontal'` (reflected) — the axis used at/above
   `orientationBreakpoint` (or always, when that's unset).
@@ -4567,6 +4835,10 @@ position) survives the transition.
   view externally; also updated internally when a view toggle is clicked.
 - `accessibleLabel: string = ''` (attribute `aria-label`) — overrides the label-derived fullscreen
   dialog name.
+- `storageKey?: string` (attribute `storage-key`) — when set, persists `collapsed` to `localStorage`
+  under `lr-widget:${storageKey}` and restores it on the next mount (mirrors `lr-app-rail`'s/
+  `lr-table`'s identical `storage-key` pattern). Without a `storageKey` there is no persistence and
+  storage is never touched — listen for `lr-collapse-change` and persist the state yourself.
 
 **Events:** `lr-collapse-change` (`detail: { collapsed }`, the new state), `lr-fullscreen-change`
 (`detail: { fullscreen }` — also fired when fullscreen is exited via Escape or a backdrop click, not
@@ -4629,6 +4901,9 @@ space for a persistent sidebar/toolbar that should stay visible instead of being
 fullscreen panel/backdrop — it overrides the default `var(--lr-space-l)` inset on every side for
 both `[part="base"]` and `[part="backdrop"]`. Set `compact` for tighter header/body padding.
 
+The collapse-button `aria-label` is localized via its own `widgetCollapse` (default `'Collapse
+panel'`) and `widgetExpand` (default `'Expand panel'`) keys.
+
 **Known gotchas:**
 - a reconnect that preserves the same element instance (e.g. a drag-and-drop reparent) resumes its
   shared overlay registration and re-acquires the scroll lock if `fullscreen` was still `true`
@@ -4636,6 +4911,11 @@ both `[part="base"]` and `[part="backdrop"]`. Set `compact` for tighter header/b
   between, so `willUpdate()` alone wouldn't otherwise notice.
 - `collapsed` hides the body via `hidden` rather than an animated height transition — collapsing is
   instant, not a slide.
+- prior to this release the collapse-button `aria-label` was localized through `lr-dock-panel`'s
+  own `dockPanelCollapse`/`dockPanelExpand` keys (a borrowed, differently-named pair). A locale
+  registered against those keys specifically to target `lr-widget`'s collapse button should move
+  to `widgetCollapse`/`widgetExpand`; the default English strings are unchanged, and `lr-dock-panel`
+  itself is unaffected.
 
 ---
 
@@ -5102,6 +5382,13 @@ labeled options, rendered as a button row" is ubiquitous settings/filter-panel U
 **Events:** `lr-change` (`detail: { value }`) — fired when the selected value changes via click or
 keyboard.
 
+**Methods:**
+- `scrollToValue(value: string): void` — scroll the segment with the given `value` into view within
+  the (possibly overflowing) track, without changing the selection. Honors
+  `prefers-reduced-motion` (falls back to `behavior: 'auto'`). This runs automatically when `value`
+  is changed programmatically (keyboard navigation already reveals the focused segment on its own),
+  so you only need to call it for the "reveal without selecting" case.
+
 **Slots:** none.
 
 **CSS parts:** `base` (the `role="radiogroup"` root), `segment` (a single `role="radio"` button),
@@ -5408,8 +5695,10 @@ content is never duplicated.
 
 Opting in to `resizable` adds a continuously draggable width for the `'full'` state: a
 `[part="resizer"]` handle (pointer-drag and Left/Right-arrow keyboard stepping, RTL-aware) clamped to
-`[minRailWidthPx, maxRailWidthPx]`, with no built-in persistence — a consumer that wants the chosen
-width to survive a reload listens for `lr-rail-resize` and persists `railWidthPx` itself.
+`[minRailWidthPx, maxRailWidthPx]`. Set `storageKey` (attribute `storage-key`) to persist `open` and
+`railWidthPx` to `localStorage` under `lr-app-rail:${storageKey}` and restore them on the next mount
+(mirrors `lr-split`'s `storage-key`; `mode` is breakpoint-derived and never persisted). Without a
+`storageKey` there is no persistence — listen for `lr-rail-resize` and persist `widthPx` yourself.
 `preferredMode` separately lets a host manually prefer `'full'`/`'icon-only'` for the non-mobile
 breakpoint axis (e.g. a user's own collapse toggle) while `mobile-breakpoint` continues to be tracked
 automatically regardless — it's only consulted while `mode` isn't force-pinned via the `mode`
@@ -5454,6 +5743,9 @@ accessor itself, which still takes full priority.
 - `railWidthPx?: number` (attribute `rail-width-px`) — the rail's current width in px while
   `resizable`; settable/gettable directly. Unset defers to `--lr-app-rail-width`'s own resolved
   width.
+- `storageKey?: string` (attribute `storage-key`) — when set, persists `open` and `railWidthPx` to
+  `localStorage` under `lr-app-rail:${storageKey}` and restores them on the next mount. `mode` is
+  breakpoint-derived and never persisted. Unset means no persistence.
 - `minRailWidthPx: number = 190` (attribute `min-rail-width-px`) — minimum `railWidthPx` a
   drag/keyboard resize can reach.
 - `maxRailWidthPx: number = 440` (attribute `max-rail-width-px`) — maximum `railWidthPx` a
@@ -6047,6 +6339,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**
@@ -6338,7 +6635,7 @@ From the `toaster` controller — the ergonomic entry point, no manual `<lr-toas
 needed:
 
 ```ts
-import { toast } from '@aceshooting/lyra-ui';
+import { toast } from '@aceshooting/lyra-ui/components/overlays/toast/toaster.js';
 
 toast('Saved');
 toast({ message: 'Deleted', variant: 'danger', action: { label: 'Undo', onClick: (item) => {/*...*/} } });
@@ -6353,7 +6650,7 @@ at another, since `placement` is a per-call option rather than a single global r
 
 ```html
 <script type="module">
-  import { toast } from '@aceshooting/lyra-ui';
+  import { toast } from '@aceshooting/lyra-ui/components/overlays/toast/toaster.js';
   document.getElementById('save-btn').addEventListener('click', () => toast('Saved!'));
 </script>
 ```
@@ -6401,7 +6698,9 @@ the existing `flex-start` cross-axis and `start` text alignment, and `center` ce
 `--lr-empty-compact-padding` (default `--lr-space-xs` — padding used in compact mode),
 `--lr-empty-compact-gap` (default `--lr-space-2xs` — gap between the icon, heading, and description
 in compact mode; the non-compact layout's gap stays the plain shared `--lr-space-s` token, not
-independently themeable), plus shared tokens (`--lr-space-xs/-s/-l`,
+independently themeable), `--lr-empty-compact-font-size` (compact mode only; unset by default with
+**no fallback value** — the compact heading keeps its ordinary inherited font size until a
+consumer explicitly sets this token), plus shared tokens (`--lr-space-xs/-s/-l`,
 `--lr-color-text-quiet/-border/-text`).
 
 **Optional peer deps:** none.
@@ -6918,6 +7217,9 @@ near the virtual point) when one is available to give it something to observe; o
 the anchor point moves on its own (e.g. a graph pan/zoom tick), re-call `showAt()` with fresh
 coordinates to re-anchor — the popover stays open across such a call. A popover that never calls
 `showAt()` behaves exactly as before.
+`hide(options?: { focusTrigger?: boolean })` programmatically closes the popover; pass
+`{ focusTrigger: true }` to return focus to the slotted trigger (as Escape does), or omit it to
+close without moving focus (as a bare `el.open = false` does). No-op when already closed.
 **Events:** `lr-show`, `lr-hide`. **Slots:** `trigger`, default content. **CSS parts:** `trigger`,
 `popup`, `content`. **Themeable custom properties:** `--lr-overlay-max-inline-size` (default
 `--lr-size-20rem` — maximum inline size of the popup).
@@ -8475,12 +8777,24 @@ accepted), `'size'` from `maxFileSize`, or `'directory'` for a dropped folder. `
 when the semantic dropzone (the actual keyboard-focusable element, not the hidden native `<input>`)
 gains/loses focus.
 
+Each rejected file also renders as its own line in the visible `[part="rejection"]` alert, naming
+the file and the reason via one of four locale keys: `fileInputRejectedType` (default
+`'{filename}: this file type is not accepted.'`), `fileInputRejectedSize` (default
+`'{filename}: this file is too large.'`), `fileInputRejectedCount` (default `'{filename}: only one
+file can be selected at a time.'`), and — for `'directory'` — the pre-existing
+`fileInputFolderRejected` (default `'Folders are not accepted here.'`, reused verbatim, so it has no
+`{filename}` placeholder). The filename is interpolated as caller-supplied data, never localized
+itself. The region is cleared (and unrendered) as soon as a subsequent selection rejects nothing.
+
 **Slots:** default slot — custom dropzone content, overrides the `label` attribute text when
 provided. The accessible name always comes from `label` regardless, so icon-only slot content still
 announces correctly.
 
 **CSS parts:** `base`, `input`, `status` (a visually-hidden `role="status" aria-live="polite"`
-element carrying the drag accept/reject announcement)
+element carrying the drag accept/reject announcement and the aggregate accepted/rejected count),
+`rejection` (a **visible** `role="alert"` region, rendered only while a rejection exists, listing
+each currently-rejected file next to a per-reason message — in addition to, never in place of, the
+sr-only `status` summary above)
 
 **Themeable custom properties:** `--lr-file-input-compact-padding` (default `var(--lr-space-s)`) —
 `[part='base']`'s padding while `compact`; `--lr-file-input-compact-gap` (default
@@ -9393,15 +9707,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
@@ -9415,6 +9741,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.
@@ -9427,11 +9763,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
-
-**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)
+- `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()`, 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 —
@@ -9477,10 +9827,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),
@@ -9585,16 +9934,24 @@ passthrough). Not a subclass of `LyraChart`.
   every bar/segment at that index, across every dataset — e.g. to highlight a whole selected week's
   column in a stacked chart. Empty (the default) reproduces the exact existing output: no bar
   carries `data-selected`. This component takes no opinion on what the highlight looks like, only
-  which bars it applies to — style it via `::part(bar)[data-selected]`.
+  which bars it applies to — style the highlight via the `--lr-lite-chart-selected-outline-color`
+  custom property (documented below). Note `::part(bar)[data-selected]` is **invalid CSS** — Shadow
+  Parts forbids an attribute selector after `::part()` — so it silently never matches; the outline
+  is painted inside the shadow root and exposed through that token instead.
 - `minBarHeight?: number` (attribute `min-bar-height`) — optional minimum visible bar height for
   small non-zero values
 - `accessibleLabel?: string` (attribute `accessible-label`) — SVG accessible-name override; a host
   `aria-label` wins
+- `appendData(label, values, maxPoints?)` — appends one aligned category and optionally trims the
+  oldest categories
 
 **Events:** `lr-point-click` — fired when a bar/point is activated (click, or Enter/Space while
 focused). `detail: { datasetIndex: number, index: number, label: string | undefined, value: number
 | null }` — same shape as `lr-chart`'s `lr-point-click`.
 
+**Methods:** `exportData('csv' | 'svg')` returns a spreadsheet-safe CSV snapshot or the current SVG
+markup. The method does not download a file; pair it with `lr-export-button` for download UX.
+
 The axis gutter/title and y-axis labels mirror to logical start under RTL. Built-in mark summaries
 are complete localized templates and format values with `effectiveLocale`.
 
@@ -9609,7 +9966,16 @@ fresh, small SVG render is cheaper and more correct than a lossy cache.
 `data-selected` when its category index is in `selectedIndex`), `line`, `point`, `legend`,
 `legend-item`, `legend-swatch`, `legend-text` (extra per-item text after the series label,
 rendered only when `legendText` is set), `live-region` (the current mark announcement for keyboard
-users), `data-list` (a visually hidden list of all plotted data points).
+users), `data-list` (a visually hidden list of all plotted data points — single-series only),
+`data-table` (a visually hidden category×series data table, rendered instead of `data-list` when
+there is more than one dataset).
+
+**Screen-reader data alternative:** a single dataset renders the flat `data-list` (one `<li>` per
+plotted point, matching the roving-tabindex mark order). More than one dataset instead renders a
+`data-table` — a category-labelled `<caption>` (the shared localized `chartData` string), one
+`<th scope="col">` per series (plus a leading `chartCategory` corner header), and one
+`<th scope="row">` per category label with its per-series values in the body — so a screen-reader
+user hears the values grouped by series rather than one flattened N×M sequence.
 
 **Themeable custom properties:** `--lr-chart-height` (same host-level property as `lr-chart`);
 `--lr-chart-grid-color`, `--lr-chart-tick-color`, `--lr-chart-legend-color` — same token
@@ -9664,7 +10030,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.
@@ -9685,7 +10052,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>
@@ -9729,8 +10096,9 @@ Bins `values` into `bins` equal-width buckets and renders as a bar chart (extend
 - All other `LyraChart` properties are inherited and usable: `legend`, `legendPosition` (attribute
   `legend-position`), `valueFormatter`, `area`, `zoom`, `config`, `height`, `xLabel` (`x-label`),
   `yLabel` (`y-label`), `y2Label` (`y2-label`), `beginAtZero` (`begin-at-zero`), `horizontal`,
-  `stacked`, `accessibleLabel` (`accessible-label`), `accessibleDescription`
-  (`accessible-description`), `showDataTable` (`show-data-table`), `chartArea` (readonly).
+  `stacked`, `dataLabels` (`data-labels`), `stackTotals` (`stack-totals`), `accessibleLabel`
+  (`accessible-label`), `accessibleDescription` (`accessible-description`), `showDataTable`
+  (`show-data-table`), `chartArea` (readonly).
 
 **Methods:** `resetZoom()`, `refreshTheme()` — both inherited.
 
@@ -9794,7 +10162,8 @@ browser). Does **not** extend `LyraChart` — a deliberately bespoke API.
 
 **Slots:** `data-table` — an optional consumer-provided accessible table alternative.
 
-**CSS parts:** `base`, `canvas`, `description`, `data-table`
+**CSS parts:** `base`, `canvas`, `description`, `data-table`, `error` (`role="alert"` message shown
+instead of `canvas` when the optional box-plot peer fails to load)
 
 **Themeable custom properties:** `--lr-chart-height`, `--lr-chart-grid-color`,
 `--lr-chart-tick-color`, `--lr-chart-legend-color`, `--lr-chart-tooltip-bg`,
@@ -9821,10 +10190,19 @@ independently of the base `chart-loader.ts`).
   logical start in RTL, canvas tooltip/axis colors are token-driven, and animation is disabled
   under reduced motion.
 - If `@sgratzl/chartjs-chart-boxplot` fails to load, the component warns to the console and
-  resolves to no chart rather than throwing.
+  fails closed with a localized `role="alert"` error part rather than leaving a blank canvas.
 
 ---
 
+## Chart streaming and export
+
+`lr-lite-chart` and `lr-chart` expose additive imperative helpers for live dashboards:
+`appendData(label, values, maxPoints?)` appends one aligned category and optionally trims the oldest
+points. `lr-lite-chart.exportData('csv' | 'svg')` returns a spreadsheet-safe CSV snapshot or the
+current SVG markup. `lr-chart.exportData('csv' | 'png')` returns a CSV snapshot or Chart.js's current
+PNG data URL when the optional peer is loaded. These helpers do not download files; compose them
+with `lr-export-button` so the host owns filenames and download policy.
+
 # Document & file viewers (`components/viewers/`)
 
 ## `lr-document-preview`
@@ -9992,9 +10370,10 @@ available, the region becomes a standard `role="progressbar"` instead, self-desc
   just via two different mechanisms depending on timing.
 - `download-link` (and thus `lr-download`) only renders/fires when `src` is set — a generic-fallback
   state with no `src` shows only the file glyph and message, with no download affordance at all.
-- `download-link` also never renders for a `data:` URL, even though `data:` is accepted for text/image
-  sinks — a `src="data:..."` document renders/fetches fine but falls back to no download affordance
-  in the generic state.
+- `download-link` also never renders for a `data:` or `mailto:` URL, even though `data:` is accepted
+  for text/image sinks and `mailto:` is accepted for navigation anchors elsewhere in the library — a
+  `src="data:..."` document renders/fetches fine but falls back to no download affordance in the
+  generic state, and a `mailto:` names no retrievable bytes so it cannot be a download target at all.
 - A `src` that fails its sink's URL-safety check does **not** raise `lr-render-error` — that event is
   reserved for a `fetch()` that was actually attempted and failed at the network layer; an unsafe/
   malformed `src` is silently treated as unusable instead (a rendered `[part="error"]` message for
@@ -10144,7 +10523,12 @@ Remote resources are capped at 25 MB; exceeding it surfaces the localized
 
 **Properties:** `src`, `name`, and `maxHeight` (attribute `max-height`) are strings. `foldQuotes:
 boolean = false` (attribute `fold-quotes`) — collapses trailing quoted-reply text/HTML behind a
-localized show/hide toggle. `false` (the default) preserves the full body rendering.
+localized show/hide toggle. `false` (the default) preserves the full body rendering. 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 message text and emit the shared search/anchor events.
 
 **Events:** `lr-render-error` with `detail.error` when fetching or parsing fails.
 `lr-attachment-open` — `detail: { attachment: { filename, mimeType, content? } }`, `content` a
@@ -10174,7 +10558,12 @@ contract: an absent `postal-mime` renders `[part="error"]` with the localized
 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.
 
@@ -10198,12 +10587,17 @@ read straight from JSZip's local file header (`uncompressedSize`) when available
 fully decompressing only the rare entry missing that header field. The list composes
 `<lr-virtual-list>` for large archives.
 
-**Properties:** `src` and `name` are strings — `name` (or a host-level `aria-label`) names the
-listing region as `role="region"`; with neither set, the region is unnamed.
+**Properties:** `src` and `name` are strings — a host-level `aria-label` takes precedence over
+`name` when naming the `role="region"` listing. The viewer also exposes the shared text-viewer
+contract: `highlights`, `activeHighlightId`, `anchor`, and `anchorKinds` (`['text-quote', 'fragment']`).
+
+**Methods:** `search(query)`, `searchNext()`, `searchPrevious()`, and `clearSearch()` provide
+case-insensitive text search over rendered entry names; `scrollToAnchor()` resolves text-quote and
+fragment anchors and emits `lr-anchor-result`.
 
 **Events:** `lr-render-error` with `detail.error` when fetching or parsing fails.
 
-**CSS parts:** `base`, `entry`, `entry-icon`, `entry-name`, `entry-name-dir`, `entry-size`,
+**CSS parts:** `base`, `body`, `entry`, `entry-icon`, `entry-name`, `entry-name-dir`, `entry-size`,
 `spinner`, and `error`. A directory row's name element carries both `entry-name` and
 `entry-name-dir` (a part list), so `::part(entry-name-dir)` selects only directory names while
 `::part(entry-name)` still selects every name. Entry rows are rendered into the embedded
@@ -10276,10 +10670,14 @@ Best-effort client-side PPTX viewer backed by the optional `@aiden0z/pptx-render
 localized fidelity notice is always visible because animations, equations, embedded objects,
 speaker notes, and several advanced effects are not rendered.
 
-**Properties:** `src`, `name`, and `label` are strings. A host `aria-label` also names the viewer
-region when `label` is unset.
+**Properties:** `src`, `name`, and `label` are strings. A host `aria-label` takes precedence over
+`label` and `name`. `highlights`, `activeHighlightId`, `anchor`, and `anchorKinds`
+(`['text-quote', 'fragment']`) provide the shared text-viewer contract when the renderer exposes
+DOM text.
 
 **Methods:** `goToSlide(index)` returns a promise and navigates the mounted presentation.
+`search(query)`, `searchNext()`, `searchPrevious()`, `clearSearch()`, and `scrollToAnchor()` are
+available for renderer output that exposes DOM text.
 
 **Events:** `lr-load` (`detail: { slideCount }`), `lr-slide-change` (`detail: { index, count }`),
 and `lr-render-error` with `detail.error`.
@@ -10343,7 +10741,12 @@ Remote resources are capped at 25 MB; exceeding it surfaces the localized
 Fetches an HTML document, sanitizes it with the optional `dompurify` peer, and renders the safe markup
 inside a bounded, scrollable body.
 
-**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 sanitized HTML text and emit the shared search/anchor events.
 
 **Events:** `lr-render-error` with `detail.error` when fetching or sanitizing fails.
 
@@ -10419,7 +10822,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.
 
@@ -10635,6 +11043,11 @@ removed once it settles either way. Build error UI from `lr-include-error`.
   letting `fetch()` throw. `no-cors` is accepted for enum completeness but always yields an opaque
   response (`status` `0`, unreadable body) — a Fetch API limitation, not a bug here.
 
+The shared text-viewer contract is also available for the sanitized light-DOM fragment:
+`highlights`, `activeHighlightId`, `anchor`, and `anchorKinds` (`['text-quote', 'fragment']`).
+`search(query)`, `searchNext()`, `searchPrevious()`, `clearSearch()`, and `scrollToAnchor()`
+operate on the included text.
+
 **Events:**
 - `lr-load` — `detail: { src }` — the fragment was sanitized and written into the light DOM.
 - `lr-include-error` — `detail: { status, reason, error? }`. `reason` is a `LyraIncludeErrorReason`:
@@ -10878,7 +11291,10 @@ collapsed-depth="2">` of the raw value instead of the map.
 
 **Properties:** `src: string = ''` — URL to fetch and parse. `name: string = ''` — accessible label,
 used as `<lr-map>`'s `label` and the root's `aria-label` (falling back to the localized
-`geojsonViewLabel` when unset).
+`geojsonViewLabel` when unset). A host `aria-label` takes precedence over `name`. The shared
+text-viewer contract adds `highlights`, `activeHighlightId`, `anchor`, and
+`anchorKinds` (`['text-quote', 'fragment']`), plus `search()`, `searchNext()`, `searchPrevious()`,
+`clearSearch()`, and `scrollToAnchor()` for rendered feature metadata and status text.
 
 **Events:** `lr-render-error` — `detail: { error }` — fetch, parse, or shape-validation failure.
 
@@ -11240,6 +11656,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.
@@ -11313,10 +11734,13 @@ variant), `cursor` (the blinking bar in the `cursor` variant)
 `size="sm"`), `--lr-typing-gap` (default `0.25rem`, `0.1875rem` at `size="sm"`),
 `--lr-typing-cursor-width` (default `0.125rem`, `0.09375rem` at `size="sm"`),
 `--lr-typing-cursor-height` (default `1em`, unaffected by `size`),
-`--lr-typing-dot-stagger-1` (default `600ms`, second dot), and
-`--lr-typing-dot-stagger-2` (default `1200ms`, third dot). Every variant uses the shared
-`--lr-transition-ambient` compound duration/timing token (default `1.8s ease-in-out`) as its
-animation cycle.
+`--lr-typing-dot-stagger-1` (default `600ms`, second dot), `--lr-typing-dot-stagger-2` (default
+`1200ms`, third dot), and `--lr-typing-duration` (default `var(--lr-transition-ambient)`, i.e.
+`1.8s ease-in-out`) — the compound duration/timing-function token every variant uses as its
+animation cycle. `--lr-typing-duration` is a dedicated alias: it defaults to the library-wide
+`--lr-transition-ambient` token (shared by every other ambient-looping component), but overriding
+it retimes only this component, leaving `--lr-transition-ambient` itself — and anything else keyed
+off it — untouched.
 
 **Optional peer deps:** none.
 
@@ -11325,7 +11749,7 @@ animation cycle.
 <lr-typing-indicator variant="pulse" size="sm"></lr-typing-indicator>
 <lr-typing-indicator variant="cursor"></lr-typing-indicator>
 <lr-typing-indicator
-  style="--lr-transition-ambient: 900ms ease-in-out; --lr-typing-dot-stagger-1: 300ms; --lr-typing-dot-stagger-2: 600ms"
+  style="--lr-typing-duration: 900ms ease-in-out; --lr-typing-dot-stagger-1: 300ms; --lr-typing-dot-stagger-2: 600ms"
 ></lr-typing-indicator>
 ```
 
@@ -11344,9 +11768,10 @@ decorative; `label` is the entire accessible content, nothing narrates individua
   state (`opacity: 1`, no transform, `animation: none !important`) rather than freezing on whatever
   frame the animation happened to be on — notably relevant for `cursor`, which would otherwise risk
   freezing on its invisible ("off") blink half.
-- `--lr-transition-ambient` is a compound `duration timing-function` value and cannot be divided
-  with `calc()`. When retiming it, override both stagger properties alongside it to preserve the
-  default one-third/two-thirds dot phasing, as shown above.
+- `--lr-typing-duration` (like the `--lr-transition-ambient` token it aliases by default) is a
+  compound `duration timing-function` value and cannot be divided with `calc()`. When retiming it,
+  override both stagger properties alongside it to preserve the default one-third/two-thirds dot
+  phasing, as shown above.
 - `size="sm"` shrinks the dot size, gap, and cursor width, but **not** `--lr-typing-cursor-height`
   (still `1em` at any size) — the cursor bar's height is meant to track surrounding text size via
   `1em`, not the component's own `size` property.
@@ -11674,8 +12099,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`
@@ -11694,6 +12119,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
@@ -11875,7 +12307,13 @@ decorative box size (clamped against `--lr-icon-button-size` via `min()`). All f
 uses — so `size` is the primary lever; override the cssprop directly only to retune a single tier or
 step outside the scale entirely. `--lr-model-select-option-active-bg` (default
 `var(--lr-color-brand-quiet)`) — background of a hovered or keyboard-active `[part="option"]` row;
-declared as a `var()` fallback at the point of use, not on `:host`, so it isn't tied to `size`. Plus
+declared as a `var()` fallback at the point of use, not on `:host`, so it isn't tied to `size`. The
+selected row (`[part="option"][aria-selected="true"]`) has the matching set
+`--lr-model-select-option-selected-bg` (default `transparent`),
+`--lr-model-select-option-selected-border` and `--lr-model-select-option-selected-color` (both
+`var(--lr-color-brand)`), and `--lr-model-select-option-selected-font-weight`
+(`var(--lr-font-weight-semibold)`), all inline `var()` fallbacks so the selected row is rethemeable
+without hijacking `--lr-color-brand`. Plus
 shared tokens — `--lr-space-xs/-s`, `--lr-color-border/-surface/-brand/-brand-quiet/-text-quiet`,
 `--lr-radius`, `--lr-shadow`, `--lr-focus-ring-width/-color/-offset`, `--lr-icon-button-size`,
 `--lr-transition-fast`, `--lr-opacity-disabled`.
@@ -12884,7 +13322,7 @@ reach callback-rendered descendants through these parts). `row-excerpt` wraps `r
 output, which is slotted into the row item's own `excerpt` slot.
 
 Data mode additionally forwards each row `<lr-conversation-item>`'s own parts under a `row-item-`
-prefix: `row-item-base`, `row-item-option`, `row-item-leading`, `row-item-content`,
+prefix: `row-item-base`, `row-item-active-indicator`, `row-item-option`, `row-item-leading`, `row-item-content`,
 `row-item-title`, `row-item-title-input`, `row-item-rename-button`, `row-item-excerpt`,
 `row-item-meta`, `row-item-timestamp`, `row-item-actions`.
 
@@ -13300,6 +13738,11 @@ referenced: `--lr-color-text-quiet`, `--lr-color-surface`, `--lr-color-border`,
 `--lr-space-xs/-s/-m`, `--lr-radius`, `--lr-shadow`, `--lr-focus-ring-*`,
 `--lr-transition-fast`.
 
+> Retheming a chip from outside `<lr-tool-call-chip>` (e.g. per-tool or per-status 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
@@ -13366,6 +13809,13 @@ shell around it.
 - `copyable: boolean = false` (reflected) — shows a copy-to-clipboard affordance alongside the
   fallback view, for either `fallback` kind: forwarded to `<lr-json-viewer>`'s own `copyable` for
   `"json"`, or a `<lr-copy-button>` rendered next to the text for `"text"`.
+- `status: 'pending'|'running'|'success'|'error'|'denied' = 'success'` (reflected) — the outcome of
+  the currently-rendered result, as reported by the matched renderer's own `context.reportStatus()`
+  (see below). Reset to `'success'` immediately before every `render()` call, so a renderer that
+  never calls `reportStatus` — including every pre-existing 2-arg renderer written before this
+  property existed — leaves it at that default, and a later renderer that stays quiet doesn't
+  inherit a stale outcome left behind by a previous one. Same status vocabulary as
+  `<lr-tool-result-dialog>`/`<lr-tool-call-chip>`.
 
 **Events:** `lr-render-error` (`detail: { toolName: string; error: unknown }`) — fired immediately
 before falling back to `<lr-json-viewer>`, whether because no renderer matched, a candidate
@@ -13408,10 +13858,16 @@ this same module-level registry unless a given `<lr-tool-result-view>`'s `regist
 set to a different `Map` instance.
 
 **`ToolRendererDefinition`** — the shape of one registered renderer:
-- `render?: (result: unknown, args: unknown) => unknown` — renders the result (and the args that
-  produced it) as UI. Typed as `unknown` rather than Lit's `TemplateResult` so any lit-html-renderable
-  value works (a plain string, a DOM node, an array of templates) — consumers already own their own
-  Lit import and don't need this module to add one
+- `render?: (result: unknown, args: unknown, context: ToolRenderContext) => unknown` — renders the
+  result (and the args that produced it) as UI. Typed as `unknown` rather than Lit's
+  `TemplateResult` so any lit-html-renderable value works (a plain string, a DOM node, an array of
+  templates) — consumers already own their own Lit import and don't need this module to add one.
+  The 3rd `context` argument is additive: it's the *last* positional parameter, so a pre-existing
+  2-arg `render(result, args)` function stays assignable to this type unchanged — JS/TS function
+  assignability allows an implementation with fewer parameters than its declared type. Use
+  `context.reportStatus(status)` (see `ToolRenderContext` below) to signal a non-throwing outcome
+  — e.g. an application-level failure the renderer still drew real UI for — instead of throwing,
+  which discards that UI for the `<lr-json-viewer>` fallback instead
 - `matches?: (payload: unknown) => boolean` — facade/shape-based dispatch predicate, consulted only
   when no exact `toolName` key matches (see dispatch order below); only ever consulted *before*
   `load` resolves when supplied inline at registration time — a definition that needs shape-based
@@ -13424,6 +13880,27 @@ set to a different `Map` instance.
   object, so `load: () => import('./my-renderer.js')` works unmodified when that module's default
   export is itself a `ToolRendererDefinition`
 
+**`ToolRenderContext`** — the shape of `render()`'s 3rd argument:
+- `reportStatus: (status: ToolResultStatus) => void` — reports this render's outcome without
+  throwing. `ToolResultStatus` is `'pending' | 'running' | 'success' | 'error' | 'denied'`, the same
+  union `<lr-tool-result-dialog>`/`<lr-tool-call-chip>` use, re-exported from this module. Calling
+  it is entirely optional: a renderer that never calls it leaves `<lr-tool-result-view>`'s `status`
+  property at its default, `'success'`. This threads through the lazy `load()` path exactly the
+  same way — a `render()` resolved via `load()` receives the same 3rd `context` argument as one
+  registered directly.
+
+```ts
+registerToolRenderer('run_query', {
+  render: (result, _args, context) => {
+    if ((result as { rows?: unknown[] })?.rows === undefined) {
+      context.reportStatus('error');
+      return html`<p class="query-error">The query returned no result set.</p>`;
+    }
+    return html`<query-result-table .rows=${(result as { rows: unknown[] }).rows}></query-result-table>`;
+  },
+});
+```
+
 **Exports:**
 - `registerToolRenderer(name: string, def: ToolRendererDefinition): void` — registers (or
   overwrites) the renderer for `name` in the module-level default registry
@@ -13483,6 +13960,20 @@ registerToolRenderer('web_search', {
 - `matches` is a linear scan over every registered definition's `matches` in registration order; it
   only runs when the exact-name lookup misses, so tool names with a direct registration never pay
   that scan cost
+- `status` is reset to `'success'` immediately before every `render()` call, not merely at
+  construction — a renderer that reported `'error'` on one result does not leave that status
+  behind once dispatch moves on to a different (quiet) renderer; a `reportStatus()` call that
+  arrives asynchronously after a *newer* resolve has already started (a stale promise the previous
+  render kicked off) is detected via the same generation counter as the `load()` staleness guard
+  and discarded rather than clobbering the newer status
+- **don't type a custom renderer against a hand-rolled, over-generic function signature** (e.g.
+  `render: (...args: any[]) => unknown`, or a locally-declared narrower alias then cast to
+  `ToolRendererDefinition`) — write the registration as a plain object literal (as in every example
+  above) or annotate it as `ToolRendererDefinition` directly, so TypeScript checks the actual
+  current `render`/`matches`/`load` shape, including the `context: ToolRenderContext` 3rd
+  parameter and the exact `ToolResultStatus` string union `reportStatus` accepts. A loosened/`any`
+  signature type-checks either way but silently gives up the compiler's ability to catch a typo'd
+  status string or a dropped `context` parameter
 - `fallback` implements exactly two kinds, `"json"` and `"text"`; any *other* value silently behaves
   as `"json"`, as does `"text"` whenever `result` isn't a string. Only `"text"` renders
   `[part="fallback-text"]`/`[part="fallback-copy"]`
@@ -15064,6 +15555,38 @@ retinted independently; `--lr-tool-timeline-pending-approval-border-color` (defa
 `var(--lr-color-warning)`) — color of the entry body's leading border while that entry's
 `data-pending-approval` is `"true"`.
 
+## `lr-agent-eval-dashboard`
+
+Controlled evaluation overview with metric cards, a dependency-free trend chart, and run-status
+history. It never launches or scores evaluations.
+
+**Properties:** `metrics: AgentEvaluationMetric[] = []` (attribute: false), where each metric is
+`{ id, label, value, format?: 'number' | 'percent' | 'milliseconds' | 'currency' }`; `runs:
+AgentEvaluationDashboardRun[] = []` (attribute: false), where each run is `{ id, label, status,
+metrics?: Record<string, number> }`; `metricId: string = ''`; `label: string = ''`; `showChart:
+boolean = true`; `chartHeight: string = '220px'`.
+
+**Events:** `lr-metric-change` (`{ metricId }`, reserved for host-controlled metric selectors) and
+`lr-run-select` (`{ runId }`).
+
+**CSS parts:** `base`, `heading`, `metrics`, `metric`, `chart`, `runs`, `runs-heading`, `run`,
+`run-label`, `run-meta`, `run-status`, `empty`.
+
+## `lr-approval-queue`
+
+Keyboard-accessible queue of pending tool calls backed by one reusable `lr-tool-approval-dialog`.
+It never executes tools or persists decisions.
+
+**Properties:** `requests: ToolApprovalRequest[] = []` (attribute: false), where each request is
+`{ id, toolName, args, status?: 'pending' | 'approved' | 'denied' }`; `selectedId: string = ''`;
+`open: boolean = false`; `editable: boolean = true`; `label: string = ''`.
+
+**Events:** `lr-approval-select` (`{ invocationId }`), `lr-approval-decision` (`{ invocationId,
+approved, args? }`), and `lr-approval-close` (`{ invocationId, reason }`).
+
+**CSS parts:** `base`, `heading-row`, `heading`, `count`, `list`, `request`, `request-info`,
+`tool-name`, `request-id`, `status`, `empty`.
+
 # Retrieval, knowledge graph & grounding (`components/retrieval/`)
 
 ## `lr-graph`
@@ -15939,6 +16462,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
@@ -16687,3 +17215,54 @@ falls back to that token, so rendering is unchanged. Plus shared tokens otherwis
 **Known gotchas:**
 - Every stage starts collapsed; expansion state is internal `@state` keyed by stage id, not a
   controlled property.
+
+## `lr-rag-answer`
+
+Controlled grounded-answer surface combining sanitized Markdown, citation badges, grounding
+assessment, and expandable source previews. It performs no model call, retrieval, citation parsing,
+or source fetching.
+
+**Properties:** `answer: string = ''`; `citations: Citation[] = []` (attribute: false);
+`sources: DocumentRef[] = []` (attribute: false); `assessment: GroundingAssessment | null = null`
+(attribute: false); `loading: boolean = false`; `error: string = ''`; `showSources: boolean = true`;
+`label: string = ''`; `accessibleLabel: string | null = null` (attribute `aria-label`).
+
+**Events:** `lr-citation-select` (`{ citation }`) and `lr-retry`.
+
+**Slots:** `answer` replaces the data-driven Markdown body; `sources` replaces the data-driven
+source list.
+
+**CSS parts:** `base`, `answer`, `loading`, `error`, `retry`, `grounding`, `citations`,
+`citation-list`, `sources`, `source-list`, `section-heading`.
+
+## `lr-embedding-explorer`
+
+Dependency-free accessible 2D embedding projection viewer. Coordinates are projected by the host;
+the component only normalizes them into SVG, colors optional clusters, and emits selection events.
+
+**Properties:** `points: EmbeddingPoint[] = []` (attribute: false), where each point is `{ id, x,
+y, label?, sourceId?, cluster? }`; `selectedId: string = ''`; `height: string = '360px'`;
+`accessibleLabel: string | null = null` (attribute `aria-label`). Non-finite coordinates are
+omitted.
+
+**Events:** `lr-point-select` (`{ point }`), activated by click or Enter/Space.
+
+**CSS parts:** `base`, `plot`, `point`, `empty`.
+
+## `lr-knowledge-base-admin`
+
+Tabbed operations shell composing `lr-knowledge-base` and `lr-ingestion-queue`. It forwards source
+and ingestion actions under namespaced events; host-owned controls such as chunking, embedding,
+permissions, and connector settings go in the `settings` slot.
+
+**Properties:** `sources: KnowledgeSource[] = []` (attribute: false); `ingestionItems:
+IngestionQueueItem[] = []` (attribute: false); `activeTab: 'sources' | 'ingestion' = 'sources'`;
+`label: string = ''`; `hideIngestion: boolean = false`.
+
+**Events:** `lr-tab-change` (`{ tab }`), `lr-source-create`, `lr-source-sync`, `lr-source-pause`,
+`lr-source-delete`, `lr-ingestion-retry`, and `lr-ingestion-cancel` (the latter four preserve the
+correlated ids/details from their composed primitives).
+
+**Slots:** `settings` — host-owned KB configuration controls.
+
+**CSS parts:** `base`, `heading`, `tabs`, `tab`, `panel`, `settings`.