@aceshooting/lyra-ui 6.1.0 → 7.0.0

package/llms-full.txt

@@ -7,7 +7,7 @@ Agent UI. Selected components retain documented Web Awesome-compatible public na
 prefix to make migration easier, but Lyra has its own implementation, design tokens, localization
 runtime, RTL behavior, and release surface. It has no runtime dependency on either project.
 
-**This file is the whole catalog concatenated — 251 components, several hundred thousand tokens.**
+**This file is the whole catalog concatenated — several hundred thousand tokens.**
 Read it end to end only if you genuinely need everything. Otherwise:
 
 | To… | Read |
@@ -39,9 +39,9 @@ family and entry point.
 - **Media, files & maps** — 18 tags in `components/media/`
 - **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/`
+- **Conversation & chat UI** — 33 tags in `components/conversation/`
+- **Agent tooling, tool calls & evaluation** — 35 tags in `components/agent-tools/`
+- **Retrieval, knowledge graph & grounding** — 30 tags in `components/retrieval/`
 - **Reference tables** — design tokens (`llms/tokens.md`), optional peers (`llms/peers.md`), `wa-*`/`sl-*` migration (`llms/migration.md`)
 
 ---
@@ -58,7 +58,7 @@ import '@aceshooting/lyra-ui/components/forms/combobox/combobox.js'; // register
 import '@aceshooting/lyra-ui/components/data/table/table.js';        // registers <lr-table>
 ```
 
-`llms/index.md` lists the exact path for all 251 tags. A wrong or missing family segment is a hard
+`llms/index.md` lists the exact path for every tag. A wrong or missing family segment is a hard
 module-resolution failure, not a silent no-op — `exports` maps `./components/*` straight onto
 `./dist/components/*`.
 
@@ -71,8 +71,22 @@ module-resolution failure, not a silent no-op — `exports` maps `./components/*
   `lr-bar-chart`, `lr-pie-chart`, `lr-doughnut-chart`, `lr-radar-chart`, `lr-polar-area-chart`,
   `lr-bubble-chart`, `lr-scatter-chart`), `lr-box-plot`, `lr-histogram`, `lr-map`, `lr-graph`,
   `lr-knowledge-graph-explorer`, and `lr-geojson-view`. Those always need their own subpath import.
-  The barrel also re-exports every class and type (every `Lyra*EventMap` type included), so it is the
-  one import that defeats tree-shaking — prefer per-component entries in application code.
+  The barrel also re-exports a broad compatibility surface of commonly used classes, helpers, and
+  types, but it is not an exhaustive promise that every component-owned type or future export is
+  present. It is the one import that defeats tree-shaking — prefer the owning component entry in
+  application code, both for the smallest bundle and the complete contract of that component.
+- **Document anchor/highlight types.** The granular document-viewer entry owns and exports
+  `LyraAnchor`, `LyraAnchorKind`, `LyraHighlight`, `LyraHighlightTone`,
+  `AnchorTargetCapabilities`, `HighlightActivateDetail`, `TextSelectDetail`, and
+  `AnchorResultDetail`:
+  ```ts
+  import type {
+    LyraAnchor,
+    LyraHighlight,
+    AnchorTargetCapabilities,
+  } from '@aceshooting/lyra-ui/components/viewers/document-viewer/document-viewer.js';
+  ```
+  Use that entry instead of depending on incidental root-barrel coverage.
 - **`lr-flag`** registers from the barrel, but resolving a flag by `country`/`language` (rather than
   a pre-resolved `src`) additionally needs
   `import '@aceshooting/lyra-ui/components/media/flag/flag-peer.js';` once.
@@ -240,6 +254,98 @@ 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 reads `localStorage['lyra-theme']`.
+`createLyraThemeBootstrap({ storageKey })` returns the same kind of string for an application-owned
+key, so an existing persistence layer can reuse the pre-paint half independently of
+`setLyraTheme()`/`getLyraTheme()`. Calling the factory with no options returns the same string as
+`lyraThemeBootstrap`. The result 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>
+```
+
+Both variants expect a stored `{ mode, accent }` record, apply the same two attributes and
+`--lr-theme-accent`, and swallow 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
@@ -301,13 +407,29 @@ instead of hand-rolling state shapes — they bind field-for-field onto the comp
 adapter layer:
 
 ```ts
-import type { AgentRun, ChatMessage, ToolInvocation, RetrievalChunk } from '@aceshooting/lyra-ui/ai';
+import {
+  createAgentStreamState,
+  reduceAgentStream,
+  adaptAiSdkStream,
+  adaptAgUiEvents,
+  adaptA2UiSurface,
+  type AgentRun,
+  type ChatMessage,
+  type MessagePart,
+  type RetrievalChunk,
+} from '@aceshooting/lyra-ui/ai';
 ```
 
 - **Run/step state** — `AgentStatusKind`, `AgentStatus`, `AgentStep`, `AgentRun`
-- **Conversation** — `ChatMessage`, `ToolInvocation`
+- **Conversation** — `ChatMessage`, ordered `MessagePart` variants, `ToolInvocation`
 - **Documents & grounding** — `DocumentRef`, `Citation`, `RetrievalQuery`, `RetrievalChunk`,
-  `GroundingAssessment`
+  `RetrievalScoreBreakdown`, `GroundedClaim`, `GroundingAssessment`, `DocumentLocator`
+- **Streaming runtime** — `AgentStreamEvent`, `AgentStreamState`, `createAgentStreamState()`,
+  `reduceAgentStream()`, `reduceAgentStreamEvents()`; event ids make replay/duplicate delivery
+  deterministic, and JSON Patch application rejects prototype-mutating paths
+- **Protocol adapters** — `adaptAiSdkStream()`, `adaptAgUiEvents()`, and `adaptA2UiSurface()` map
+  structural provider events/documents onto the neutral runtime without pulling vendor SDKs into
+  the package
 - **Event payloads** — `RunLifecycleEventDetail`, `RetrievalProgressEventDetail`,
   `CitationSelectEventDetail`, `ToolApprovalEventDetail`, `CancelEventDetail`, `RetryEventDetail`,
   `ExportEventDetail`
@@ -318,15 +440,35 @@ feeds on `lr-chat-message`, `lr-tool-call-chip`, `lr-tool-result-view`, `lr-sour
 convention. The types are structural and provider-agnostic: map any vendor's payload onto them once,
 at the edge.
 
+### Task-first AI composition guide
+
+- **Render one model response:** `lr-message-parts`; use `lr-chat-message` only when the message
+  shell (avatar, author, actions) is also needed.
+- **Build the main prompt affordance:** `lr-prompt-input`; it already composes attachments,
+  model/voice/source controls, mentions/commands, and `lr-prompt-queue`.
+- **Run an agent workspace:** `lr-agent-workspace` + `reduceAgentStream()`; add
+  `lr-subagent-panel` for nested runs and `lr-mcp-app` only for executable MCP App resources.
+- **Show grounded output:** `lr-rag-answer`; pass claim records for `lr-claim-evidence`, use
+  `lr-retrieval-compare` for retrieval tuning and `lr-rag-eval-dashboard` for run metrics.
+- **Develop prompts/tools:** `lr-prompt-studio` and `lr-schema-viewer`.
+- **Build voice sessions:** `lr-realtime-session`; it composes the existing audio visualizer,
+  push-to-talk control, and transcript feed while leaving transport ownership with the host.
+
+Family registration entry points are additive: importing
+`@aceshooting/lyra-ui/components/conversation`, `/agent-tools`, or `/retrieval` registers and
+exports that complete family. Granular component entry points remain the smallest bundles and are
+preferred in production.
+
 ## Optional peer dependencies
 
-All 26 peers are optional and lazily loaded; nothing is imported eagerly. `llms/peers.md` is the
-generated component → peer table. The shared contract: a component resolves its peer through a
-dynamic `import()` on first use, rendering an `<lr-skeleton>` placeholder with `aria-busy="true"` on
-the host meanwhile; if the peer is genuinely absent it falls back to an empty/degraded render plus a
-single deduped `console.warn` — it never throws and never blocks paint. `lr-phone-input` is the
-exception: it takes a consumer-built adapter (`loadLibphonenumberAdapter()`) rather than importing
-`libphonenumber-js` itself.
+All 26 peers are optional and their implementations are loaded on demand; nothing is imported
+eagerly. `llms/peers.md` is the generated component → peer table. Loading and failure UI is
+component-specific: viewer sections document their localized loading/error/notice states, while
+`lr-include` preserves its light-DOM fallback/live region and emits `lr-include-error` when its
+sanitizer is unavailable. Some components additionally issue a deduped warning. Consult the owning
+component section instead of assuming every peer user renders an `<lr-skeleton>` or the same
+degraded state. `lr-phone-input` is the exception to dynamic peer import: it takes a consumer-built
+adapter (`loadLibphonenumberAdapter()`) rather than importing `libphonenumber-js` itself.
 
 ## Framework integration
 
@@ -545,14 +687,23 @@ shared `FormAssociated` mixin — see gotchas).
   shown when `maxRender` caps the row list; `{n}` is replaced with the hidden count)
 - `filter: OptionFilter | null = null` (attribute: false — `(option, query) => boolean`; default
   matches `label`/`searchText` case-insensitively; ignored while `source` is set)
-- `source: ComboboxSource | null = null` (attribute: false — `(query: string) =>
-  Promise<ComboboxSourceRow[]>`; when set, replaces the light-DOM `<lr-option>` list with an async
-  lookup, debounced ~200ms after each keystroke and re-run on clear/pick. `loadingText` is shown
-  while a call is in flight; a stale in-flight call that resolves after a newer one (or after
-  disconnect) is dropped via a monotonic token)
+- `source: ComboboxSource | null = null` (attribute: false — `(query: string, options: { signal:
+  AbortSignal }) => Promise<ComboboxSourceRow[]>`; when set, replaces the light-DOM `<lr-option>`
+  list with an async lookup, debounced by `sourceDelay` ms after each keystroke and re-run on
+  clear/pick. Forward `options.signal` to `fetch(url, { signal })` to cancel the request when a
+  newer query supersedes it or the element disconnects. `loadingText` is shown while a call is in
+  flight; a stale in-flight call that resolves after a newer one (or after disconnect) is dropped
+  via a monotonic token. The exported type requires the `options` parameter; an existing
+  one-parameter `(query) => …` function remains assignable under TypeScript's ordinary function
+  parameter compatibility, but consumers that need cancellation should accept and forward
+  `options.signal`.)
+- `sourceDelay: number = 200` (attribute `source-delay` — debounce in ms between the last keystroke
+  and the `source` call; `0` fires on every keystroke. Sanitized to a finite non-negative duration,
+  falling back to `200` for a non-finite value)
 - `maxRender: number = 200` (attribute `max-render` — caps how many rows render at once, always
   keeping the current selection visible even if it's outside the cap; the excess renders as one
-  `overflowText` row instead of being dropped silently)
+  `overflowText` row instead of being dropped silently. See "Large option lists" below for how to
+  size it, and when `source` is the better answer)
 - `value: string | string[]` — a getter/setter: plain `string` in single mode, `string[]` in
   `multiple` mode
 - `selectedRows: ComboboxSourceRow[]` (read-only getter) — structured rows for the current
@@ -573,11 +724,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 +750,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 +761,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 +816,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 +885,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
@@ -723,6 +913,10 @@ synchronous and fires no `input`/`change` event.
   `form.reset()` default itself is captured exclusively from that very first pass; a later pick, or
   a later batch of newly-`selected` options, never redefines what a reset restores to.
 
+**Additional API surface:**
+
+- `part="tag-label"` — The wrapping/ellipsis-safe selected-tag label.
+
 ---
 
 ## `lr-select`
@@ -734,7 +928,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.
@@ -766,29 +961,29 @@ exactly like the multi-option case, until the trigger is actually activated.
   single-option auto-commit behavior described above
 - `value: string` — a getter/setter; always a single string (no `multiple` mode)
 
+**Methods:** `focus(options?)`, `blur()`, and `click()` forward to the internal trigger button.
+
 **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`, and bubbling,
+composed `focus`/`blur` events re-dispatched from the internal trigger.
 
 **Slots:** default (`<lr-option>` children), `label`, `hint`, `error` (overrides the `errorText`
-attribute when provided)
-
-**`lr-select` deliberately has no `start`/`end` adornment slots**, unlike
-`lr-input`/`lr-combobox`/`lr-date-input`. Two reasons, both structural rather than incidental:
-its `[part='trigger']` is a native `<button>`, and HTML's content model forbids interactive
-descendants inside one — so the slot could only ever accept decorative content, a materially
-different contract from the other three that would read as the same feature; and the trigger lays
-out with `justify-content: space-between`, so injecting a leading element pushes the selected label
-into the middle of the control instead of leaving it at the start. **Instead:** put a glyph in the
-`label` slot, or compose the select into `<lr-control-group>` alongside the adornment.
+attribute when provided), `start` (non-interactive adornment before the selected-value label), and
+`end` (non-interactive adornment after the label and before the expand icon). The adornments live
+inside the native trigger `<button>`, so never place links, buttons, inputs, or other interactive
+content in either slot.
 
 When hint/error content is present, the trigger's `aria-describedby` references stable shadow-local
 IDs for both messages (error first, then hint), so the visible supporting text is part of the
 control's accessible description.
 
-**CSS parts:** `form-control`, `form-control-label`, `trigger`, `listbox`, `group-label` (a heading
-row emitted inside the listbox whenever an option's `group` differs from the previous one's — a
-presentational `<div>`, not a `role="group"`; options with an empty `group` get no heading),
+**CSS parts:** `form-control`, `form-control-label`, `trigger`, `start`, `end`, `listbox`,
+`group-label` (a heading row emitted inside the listbox whenever an option's `group` differs from
+the previous one's — a presentational `<div>`, not a `role="group"`; options with an empty `group`
+get no heading),
 `option`, `option-dot` (the leading status dot, when a row's `dotColor` is set), `option-label`,
 `option-sub` (a row's secondary line, when `sub` is set), `expand-icon`, `error`, `hint`
 
@@ -820,6 +1015,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
@@ -944,9 +1148,11 @@ Text field + calendar popover, **form-associated** via the shared `FormAssociate
   `<input>`'s computed accessible name; wins over `label`/`placeholder`/the localized `date`
   fallback in that order. Attribute-reflects from a host-level `aria-label` so a plain-markup
   consumer gets ARIA-name forwarding without setting a JS property.
-- `clearLabel: string = 'Clear'` (attribute `clear-label` — accessible label for the clear button)
-- `openLabel: string = 'Open calendar'` (attribute `open-label` — accessible label for the
-  calendar-toggle button)
+- `clearLabel: string = ''` (attribute `clear-label` — accessible label for the clear button;
+  empty uses the localized `clear` message, whose English fallback is `"Clear"`)
+- `openLabel: string = ''` (attribute `open-label` — accessible label for the calendar-toggle
+  button; empty uses the localized `openCalendar` message, whose English fallback is
+  `"Open calendar"`)
 - `dialogLabel: string = 'Choose date'` (attribute `dialog-label` — accessible name for the
   `role="dialog"` calendar popover)
 - `spellcheck: boolean = true` — forwarded to the internal `<input>`
@@ -1073,6 +1279,16 @@ and `dateTimeFormat(locale, options)`.
   (`--lr-color-on-brand`, not a hardcoded literal — safe to override `--lr-color-brand` without
   losing contrast on selected-day text).
 
+**Additional API surface:**
+
+- `--lr-date-picker-month-gap` — Gap between visible months. Default: `var(--lr-space-l)`.
+- `--lr-date-picker-header-gap` — Month-header child gap. Default: `var(--lr-space-s)`.
+- `--lr-date-picker-radius` — Calendar and control corner radius. Default: `var(--lr-radius)`.
+- `--lr-date-input-placeholder-color` — Placeholder text color. Default: `var(--lr-color-text-quiet)`.
+- `--lr-date-input-gap` — Gap between input-row children. Default: `var(--lr-space-xs)`.
+- `--lr-date-input-radius` — Input-row corner radius. Default: `var(--lr-radius)`.
+- `--lr-date-input-focus-border-color` — Focused row border color. Default: `var(--lr-color-brand)`.
+
 ---
 
 ## lr-textarea
@@ -1105,10 +1321,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
@@ -1139,8 +1374,10 @@ the shadow boundary.
 
 | Event | Detail | Description |
 | --- | --- | --- |
-| `lr-input` | `{ value: string }` | Fired on every user-driven edit. |
-| `lr-change` | `{ value: string }` | Fired on native `change` timing (blur after a committed edit). |
+| `input` | none | Native-style composed event fired on every user-driven edit. |
+| `change` | none | Native-style composed event fired at native `change` timing. |
+| `lr-input` | `{ value: string }` | Compatibility alias fired on every user-driven edit. |
+| `lr-change` | `{ value: string }` | Compatibility alias fired on native `change` timing (blur after a committed edit). |
 | `blur` | none | Re-dispatched from the internal native `<textarea>`'s own `blur` -- bubbling and composed, unlike the native event. |
 | `focus` | none | Re-dispatched from the internal native `<textarea>`'s own `focus`, for the same reason as `blur`. |
 
@@ -1173,6 +1410,10 @@ original declarative `value`, matching native `defaultValue` behavior.
   bound scrolls inside the native textarea. Auto-resize remeasures after user edits, programmatic
   `value`/`rows` changes, range edits, and container-width changes.
 
+**Additional API surface:**
+
+- `click()` — Activates the internal textarea.
+
 ---
 
 ## `lr-button`
@@ -1181,7 +1422,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
@@ -1202,19 +1463,24 @@ shadow-internal native button doesn't participate in an ancestor form's submissi
 - `loading: boolean = false` (reflected) — shows an internal spinner and disables the button without
   clearing `disabled`
 - `disabled: boolean = false` (reflected)
+- `accessibleLabel: string | null = null` (attribute `aria-label`) — accessible name forwarded
+  reactively to the internal native button or anchor; changing or removing the attribute after
+  mount updates the actual focused control
 
 The shared `m` size uses `--lr-font-size-m`. The internal button follows the host's inline size through `--lr-button-width` (default
 `100%`), and each size tier's `min-block-size` floor is exposed as its own token (see below).
 
-**Getters/methods:** `click()`, `focus(options?)`, and `blur()` — forwarded to the internal native
-`<button>`; `click()` also runs the component's submit/reset behavior.
+**Getters/methods:** `click()`, `focus(options?)`, and `blur()` — forwarded to the internal base
+element (the `<button>`, or the `<a>` in anchor mode); `click()` also runs the component's
+submit/reset behavior in `<button>` mode.
 
 **Events:** none (a plain native `click` bubbles and composes through the shadow boundary
 unmodified; disabled while `disabled` or `loading`).
 
 **Slots:** default (label content), `start` (leading icon/content), `end` (trailing icon/content).
 
-**CSS parts:** `base`, `label`, `start`, `end`, `spinner` (present only while `loading`).
+**CSS parts:** `base` (the internal native `<button>`, or an `<a>` when `href` resolves to a safe
+link), `label`, `start`, `end`, `spinner` (present only while `loading`).
 
 **Themeable custom properties:** `--lr-button-width`, `--lr-button-accent`, `--lr-button-fill`,
 `--lr-button-on-fill`, `--lr-button-border` (each swapped by the active `variant`, default
@@ -1242,6 +1508,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
@@ -1275,9 +1544,14 @@ box no matter what tier or override is in play.
 ```
 
 **Known gotchas:**
-- A host `aria-label` is forwarded to the internal button as a literal string (for an icon-only
-  button); an external `aria-labelledby`/`aria-describedby` idref is not copied across the shadow
-  boundary.
+- `accessibleLabel`/a host `aria-label` is forwarded reactively to the internal button or anchor as
+  a literal string (for an icon-only button); an external `aria-labelledby`/`aria-describedby`
+  idref is not copied across the shadow boundary.
+- Host `aria-haspopup` and `aria-expanded` values are forwarded to the internal semantic control.
+  For host `aria-controls`, targets in the host's own root are resolved through the reflected
+  element-reference API so a popup relationship survives the component's shadow boundary; browsers
+  without that API retain the forwarded string attribute as a best-effort fallback. This is what
+  lets either button serve as an `lr-menu` trigger.
 - Is form-associated (`static formAssociated = true` + `attachInternals()`), so it participates in
   an ancestor `<form>.elements` the same way `wa-button` does — a sibling text field's own
   Enter-to-submit lookup (which scans `form.elements` for a `type === 'submit'` control) finds it.
@@ -1286,9 +1560,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`)
@@ -1303,6 +1576,12 @@ With neither `accessibleLabel` nor `label` set, the name falls back to the local
 app-wide with `registerLyraLocale()` (see `llms/shared.md`); don't rely on the fallback for a
 button whose purpose isn't generic.
 
+Host `aria-haspopup` and `aria-expanded` values are forwarded reactively to the shadow-internal
+native button. Host `aria-controls` targets in the host's own root are resolved through the
+reflected element-reference API, so using `<lr-icon-button slot="trigger">` inside `<lr-menu>`
+exposes the menu relationship and expanded state on the element that actually receives focus;
+browsers without that API retain the forwarded string attribute as a best-effort fallback.
+
 **Methods:** `focus(options?)`, `blur()` — forward to the native button. `click()` also forwards to
 the native button, activating it — including this component's own `type="submit"`/`type="reset"`
 handling, since the click goes through the same `<button>` the pointer/keyboard path does.
@@ -1339,7 +1618,15 @@ 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, `--lr-icon-button-color` (default `inherit`) its icon/text color,
+`--lr-icon-button-color-hover` (default `var(--lr-icon-button-color, inherit)`) its hover-state
+foreground, and `--lr-icon-button-border` (default `0`) the complete native-button border
+shorthand. These are the same per-component indirection `lr-button`'s
+`--lr-button-fill`/`--lr-button-on-fill` provide, letting a single button be bordered and tinted
+without a `::part(button)` rule. Left unset, each falls back to the original value, so rendering is
+unchanged.
 
 ## `lr-input`
 
@@ -1366,13 +1653,21 @@ form-associated via the same `FormAssociated` mixin as `lr-textarea`. Ships the
 - `inputMode: string = ''` (attribute `inputmode`) / `enterKeyHint: string = ''` (attribute
   `enterkeyhint`) — these four are forwarded verbatim to the native input; an empty string omits
   the attribute entirely
-- `min?: number` / `max?: number` (attributes `min`/`max`) / `step?: number | 'any'` (attribute
-  `step`, accepts the native `'any'` value alongside a number) — forwarded verbatim to the native
+- `min?: number | string` / `max?: number | string` (attributes `min`/`max`) /
+  `step?: number | 'any'` (attribute `step`, accepts the native `'any'` value alongside a number)
+  — forwarded verbatim to the native
   input and validated by it. Intended for `type="number"`; `step` is equally meaningful on
   `type="time"`. On `lr-input` itself the `min`/`max` *attributes* are number-converted, so a
   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,9 +1742,25 @@ 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.
 
+**Additional API surface:**
+
+- `click()` — Activates the internal input.
+
 ## `lr-number-input`
 
 A migration-friendly numeric alias of `lr-input` — a subclass whose constructor and
@@ -1459,8 +1770,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 +1793,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 +1807,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).
@@ -1612,9 +1925,9 @@ interface PhoneNumberAdapter {
   native telephone input.
 - `countryLabel: string = 'Select'` (attribute `country-label`) — country-selector accessible name;
   the untouched default routes through the shared localized `select` message.
-- `incompleteText: string = 'The value is invalid.'` (attribute `incomplete-text`) — validation
-  message for dial-like input that can still become valid with more digits. The untouched default
-  routes through the shared localized `valueInvalid` message.
+- `incompleteText: string = 'This phone number is incomplete.'` (attribute `incomplete-text`) —
+  validation message for dial-like input that can still become valid with more digits. The
+  untouched default routes through the localized `phoneInputIncomplete` message.
 - `invalidText: string = 'The value is invalid.'` (attribute `invalid-text`) — completed-invalid
   message, localized through the same shared key while left at its default.
 - `autocomplete: string = 'tel'`, `inputmode: 'tel'|'numeric'|'text' = 'tel'`,
@@ -1721,6 +2034,17 @@ import '@aceshooting/lyra-ui/components/media/flag/flag-peer.js';
   via `::part` styling tricks, and don't expect the flag inside the open popup list — a native
   `<option>` is text-only.
 
+**Additional API surface:**
+
+- `click()` — Activate the internal telephone input unless the form control is effectively disabled.
+- `--lr-phone-input-flag-size` — Selected flag size, scaled by `size`.
+- `--lr-phone-input-glyph-size` — Country selector glyph size, scaled by `size`.
+- `--lr-phone-input-gap` — Country-trigger child gap. Default: `var(--lr-space-xs)`.
+- `--lr-phone-input-radius` — Input-wrapper corner radius. Default: `var(--lr-radius)`.
+- `--lr-phone-input-focus-border-color` — Focused row border color. Default: `var(--lr-color-brand)`.
+- `--lr-phone-input-invalid-border-color` — Invalid row border color. Default: `var(--lr-color-danger)`.
+- `--lr-phone-input-country-hover-bg` — Country trigger hover background. Default: `var(--lr-color-brand-quiet)`.
+
 ---
 
 ## `lr-time-range`
@@ -1744,6 +2068,11 @@ consumer-facing `disabled` property/attribute itself.
 - `disabled: boolean = false` (reflected)
 - `startLabel: string = 'Range start'` (attribute `start-label`) — `aria-label` for the start handle
 - `endLabel: string = 'Range end'` (attribute `end-label`) — `aria-label` for the end handle
+- `valueFormatter?: TimeRangeValueFormatter` (attribute: false) — maps each finite, clamped
+  `aria-valuenow` to optional human-readable `aria-valuetext`; called as
+  `(value, handle: TimeRangeHandle)`, where `TimeRangeHandle = 'start' | 'end'`. The formatter may
+  return `string | null | undefined`; a nullish result omits `aria-valuetext` for that handle.
+  Leaving the property unset preserves the numeric-only contract
 - `presets: TimeRangePreset[] = []` (attribute: false) — `TimeRangePreset { label: string; start:
   number; end: number }`; optional discrete presets (e.g. "Last 7 days") rendered as a
   `[part="presets"]` button row above the track — purely additive, the continuous brush is
@@ -1759,8 +2088,9 @@ key-up-commit, or when a preset button is clicked, `detail: { start, end }`)
 **CSS parts:** `base`, `track`, `range`, `handle-start`, `handle-end`, `presets`, `preset-button`
 
 **Themeable custom properties:** mostly shared tokens — `--lr-color-border`, `--lr-color-brand`,
-`--lr-color-surface`, `--lr-shadow` (track/handles), `--lr-opacity-disabled` (`:host([disabled])`
-dimming), plus (for `presets`) `--lr-color-text`, `--lr-color-on-brand` (the active preset
+`--lr-color-surface`, `--lr-shadow` (track/handles), `--lr-opacity-disabled` (`:host(:disabled)`
+dimming, including ancestor-fieldset disablement), plus (for `presets`) `--lr-color-text`,
+`--lr-color-on-brand` (the active preset
 button's text), `--lr-radius`, `--lr-space-xs/-s`, `--lr-transition-fast`,
 `--lr-focus-ring-*`.
 
@@ -1787,10 +2117,13 @@ any ancestor of the `<lr-time-range>` therefore reaches it. (The same technique
 **Optional peer deps:** none.
 
 ```html
-<lr-time-range min="0" max="1440" start="480" end="1020" step="15"></lr-time-range>
+<lr-time-range id="months" min="0" max="2" start="0" end="2"></lr-time-range>
 <script>
-  document.querySelector('lr-time-range')
-    .addEventListener('lr-change', (e) => console.log(e.detail.start, e.detail.end));
+  const months = ['April 2023', 'May 2023', 'June 2023'];
+  const range = document.getElementById('months');
+  range.valueFormatter = (value, handle) =>
+    `${handle === 'start' ? 'From' : 'Through'} ${months[value]}`;
+  range.addEventListener('lr-change', (e) => console.log(e.detail.start, e.detail.end));
 </script>
 ```
 
@@ -1807,9 +2140,9 @@ any ancestor of the `<lr-time-range>` therefore reaches it. (The same technique
   slider.
 - `aria-valuemin`/`aria-valuemax` on each handle report that handle's reachable sub-range (bounded by
   its sibling), not the full domain — matching what Home/End actually jump to.
-- No `aria-valuetext`: only raw numeric `aria-valuenow` is exposed (omitted entirely, rather than a
-  literal `"NaN"`, if `start`/`end` is non-finite), no hook for a human-readable (e.g. formatted
-  date/time) equivalent of the mapped domain.
+- `valueFormatter` is presentation-only: `aria-valuenow`, geometry, emitted values, and preset
+  matching stay numeric. Non-finite handles omit both `aria-valuenow` and `aria-valuetext` and are
+  never passed to the formatter.
 - Handles a `min > max` domain, a non-positive/non-finite `step`, and disabled-mid-drag/
   disconnect-mid-drag correctly (tested) — safe to rely on those edge cases. Concurrent drags are
   tracked per `pointerId` (not a single scalar), so a two-finger touch — one finger per handle —
@@ -1819,12 +2152,23 @@ any ancestor of the `<lr-time-range>` therefore reaches it. (The same technique
 - Non-finite domain/handle values use finite fallback geometry, and non-finite or negative steps are
   treated as unstepped; invalid values never become `NaN`/`Infinity` CSS or ARIA strings.
 - `startLabel`/`endLabel` only override each handle's `aria-label`; they don't affect
-  `aria-valuenow`/`aria-valuemin`/`aria-valuemax` (still raw numbers) or any visible text.
+  `aria-valuenow`/`aria-valuemin`/`aria-valuemax`, `valueFormatter`, or any visible text.
 - An ancestor `<fieldset disabled>` toggling is reflected via `formDisabledCallback` into
   `effectiveDisabled` (tracked separately from the consumer's own `disabled`), so re-enabling the
   fieldset correctly restores a handle that had `disabled` set explicitly by the consumer, and vice
   versa — mirrors `lr-combobox`'s identical pattern.
 
+**Additional API surface:**
+
+- `--lr-time-range-handle-size` — Visible handle diameter. Default: `14px*scale`.
+- `--lr-time-range-hit-size` — Actual drag hit-area diameter; endpoint handles are inset by half this distance so the hit geometry stays inside the host. Default: `max(24px,28px*scale)`.
+- `--lr-time-range-track-size` — Track and selected-range thickness. Default: `4px*scale`.
+- `--lr-time-range-base-size` — Brush baseline block size. Default: `1.5rem*scale`.
+- `--lr-time-range-preset-gap` — Gap between preset buttons. Default: `var(--lr-space-xs)`.
+- `--lr-time-range-preset-radius` — Preset button corner radius. Default: `var(--lr-radius)`.
+- `--lr-time-range-preset-padding` — Preset button padding, scaled by `size`.
+- `--lr-time-range-preset-font-size` — Preset button font size, scaled by `size`.
+
 ---
 
 ## `lr-swatch-picker`
@@ -1838,16 +2182,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.
 
@@ -1862,7 +2208,8 @@ swatch's interactive hit target, sized via `--lr-swatch-picker-hit-size` — def
 `[part='swatch'][aria-checked='true']`), `swatch-fill` (the filled circle inside it, sized via
 `--lr-swatch-picker-fill-size` — defaults to `--lr-size-1-5rem`, also swapped per `size` tier —
 rendered when the option has no `icon`), `swatch-icon` (the option's `icon` shape, rendered in its
-place when it has one). Exactly one of `swatch-fill`/`swatch-icon` is mounted per swatch, so the
+place when it has one, with its inherited `font-size` set to the same fill-size token so a `1em`
+glyph fills the wrapper). Exactly one of `swatch-fill`/`swatch-icon` is mounted per swatch, so the
 two never coexist.
 
 **Themeable custom properties:** `--lr-swatch-picker-selected-color` (ring color around the
@@ -1876,7 +2223,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 +2245,26 @@ and the per-tier `--lr-size-*` tokens.
 </script>
 ```
 
+For the shared gemstone accent mode, import the Lit-free palette data entry. The glyph renderer
+remains available separately from `theme/gemstones.js` for Lit templates; palette-only consumers
+do not need to load Lit. 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-data.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
@@ -1911,6 +2280,10 @@ and the per-tier `--lr-size-*` tokens.
 - the semantic `radiogroup` lives inside shadow DOM. Set `label` (preferred for reactive code) or a
   host `aria-label`; the component deliberately forwards the resulting name to that internal role.
 
+**Additional API surface:**
+
+- `--lr-swatch-picker-gap` — Gap between swatches. Default: `var(--lr-space-xs)`.
+
 ---
 
 ## `lr-checkbox`
@@ -1934,12 +2307,16 @@ visual box/checkmark. Structurally the same idea as `<lr-switch>` (form-associat
 `lr-change` alias (`detail: { checked: boolean }`). Programmatic `.checked` assignments are
 silent. Internal `focus`/`blur` are re-dispatched as bubbling, composed host events.
 
-**Methods:** `focus(options?)` and `blur()` forward to the internal checkbox control.
+**Methods:** `focus(options?)`, `blur()`, and `click()` forward to the internal checkbox control.
 
 **Slots:** default — label text, rendered next to the box. Clicking it toggles the checkbox, the
 same as clicking a native checkbox's associated `<label>`. If left empty, set `aria-label` on the
 host so the control still has an accessible name.
 
+Host `aria-describedby` is forwarded to the internal `role="checkbox"`, so an externally-owned
+description can be associated with one checkbox inside a group. The attribute is omitted from the
+internal role when unset and tracks host attribute changes.
+
 **CSS parts:** `base` (the whole interactive control, `role="checkbox"`), `box` (the small square
 showing the checkmark/indeterminate dash), `checkmark` (the checkmark or indeterminate-dash glyph),
 `label` (wrapper around the default slot)
@@ -2031,7 +2408,7 @@ control's visible, clickable label (same as `<lr-checkbox>`).
 **Events:** `lr-change` (`detail: { checked: boolean }`) — fired on a user toggle (click or
 Space/Enter); not fired for a programmatic `.checked` assignment.
 
-**Methods:** `focus(options?)` and `blur()` forward to the internal switch control.
+**Methods:** `focus(options?)`, `blur()`, and `click()` forward to the internal switch control.
 
 **Slots:**
 - default — label text, rendered next to the track. Clicking it toggles the switch, the same as
@@ -2097,10 +2474,13 @@ seamlessly right after. First-party invention (no Web Awesome equivalent).
 - `label: string = ''` — accessible name set as `aria-label` on the `role="slider"` thumb; a plain
   `aria-label` attribute on the host itself is honored as a fallback when this is left unset (matching
   `<lr-checkbox>`/`<lr-switch>`).
+- `valueFormatter?: SliderValueFormatter` (attribute: false) — maps the finite, clamped
+  `aria-valuenow` number to optional human-readable `aria-valuetext`. The formatter may return
+  `string | null | undefined`; a nullish result omits `aria-valuetext`. Leaving the property unset
+  preserves the existing numeric `aria-valuetext`.
 - `showValue: boolean = true` (attribute `show-value`) — whether to render the current numeric value as
   visible text next to the track. Not reflected; toggle it off via the `.showValue=${false}` property
-  binding — a bare `show-value="false"` content attribute is still truthy, since presence is all Lit's
-  default boolean converter checks.
+  binding or a plain `show-value="false"` content attribute.
 - Inherited from `FormAssociated`: `name: string = ''`, `value: string` (form-submitted string form),
   `disabled: boolean = false` (reflected), `required: boolean = false` (reflected).
 
@@ -2136,6 +2516,7 @@ when `show-value` is true)
   step="0.1"
   label="Temperature"
   .valueAsNumber=${0.7}
+  .valueFormatter=${(value) => `${value * 100}%`}
   @lr-input=${(e) => setDraftTemperature(e.detail.value)}
   @lr-change=${(e) => commitTemperature(e.detail.value)}
 ></lr-slider>
@@ -2154,6 +2535,9 @@ native range input either.
   value); ArrowUp/ArrowDown are never swapped, since direction only affects the horizontal inline axis.
 - Changing `min`/`max`/`step` after mount automatically re-clamps/re-snaps the current `value` in the
   next update — narrowing the domain can silently move the slider's value.
+- `valueFormatter` is presentation-only: `aria-valuenow`, the visible numeric readout, geometry,
+  form value, and emitted values stay numeric. With no formatter, `aria-valuetext` remains the
+  numeric string rendered by earlier versions; a nullish formatter result omits it.
 - A pointer drag fires `lr-input` continuously and a single `lr-change` on release; a keyboard step
   fires exactly one of each per press, but OS key-repeat while a key is held re-fires `lr-input` on
   every repeat while still only committing `lr-change` once, on the eventual keyup.
@@ -2209,16 +2593,21 @@ selected value is submitted under `name` and `required` requires at least one se
 
 **Properties:** `label`, `hint`, `errorText`, `value`, `name`, `required`, `disabled`, and
 `accessibleLabel` (`aria-label`). **Slots:** default checkboxes, `label`, `hint`, `error`.
-**Events:** `input`, `change`, and `lr-change` with `{ value: string[] }`.
+**Events:** a user toggle emits exactly one group-owned `input`, then `change`, then `lr-change`;
+all three carry `{ value: string[] }`. The owned child's corresponding events are consumed at the
+group boundary, so an ancestor does not receive a second, differently shaped sequence.
+Programmatic child/property synchronization is silent.
 **CSS parts:** `form-control`, `form-control-label`, `options`, `hint`, `error`.
 
 **`value` is a read-out of child state, not an input.** The children are the single source of
 truth. An internal sync recomputes `value` from them and reassigns it on every child toggle,
-`slotchange`, `name`/`required` change, blur, and `form.reset()` — so a host assignment is
-silently overwritten by the next of those. `connectedCallback()` runs that sync **before the first
-render**, which means even a constructor-time or template-time `.value=${…}` binding is discarded
-before anything can observe it. Assigning `value` logs a `console.warn` naming the property (once
-per group instance).
+programmatic child `checked`/`value`/`disabled` update, `slotchange`, `name`/`required` change,
+blur, and `form.reset()` — so a host assignment is silently overwritten by the next of those.
+Only a checkbox whose nearest `lr-checkbox-group` ancestor is this group contributes; a nested
+group owns its own descendants and form entries. `connectedCallback()` runs that sync **before the
+first render**, which means even a constructor-time or template-time `.value=${…}` binding is
+discarded before anything can observe it. Assigning `value` logs a `console.warn` naming the
+property (once per group instance).
 
 - **To preselect**, set `checked` on the children: `<lr-checkbox value="a" checked>`.
 - **To read the selection**, use this property or the `lr-change` event detail.
@@ -2242,7 +2631,9 @@ hit area stays fixed at `40px` across all sizes), `allowDuplicates` (`allow-dupl
 `false`), `editable` (reflected, default `false` — see below), and `delimiter: string | null` (default
 `','` — see below).
 **Slots:** `label`, `hint`, `error`.
-**Events:** `input`, `change`, `lr-add` (`detail: { value }`), `lr-remove`
+**Events:** native-style `input` and `change` (`detail: { value: string[] }`), bubbling/composed
+`focus` and `blur` re-dispatched from the internal text input, `lr-add` (`detail: { value }`),
+`lr-remove`
 (`detail: { value, index }` — cancelable; `preventDefault()` keeps the token in `value`
 unchanged), and `lr-token-edit`
 (`detail: { value, previousValue, index }` — an existing token was edited in place and committed).
@@ -2251,7 +2642,8 @@ token's text, doubling as the roving-focus edit trigger — rendered only while
 `token-editor` (the inline text field that replaces a token's text while it is open for editing —
 rendered only while `editable` and only for the token being edited), `remove` (the
 per-token remove button, floored at the shared `--lr-icon-button-size` tap size around a compact
-glyph), `input`, `hint`, `error`. `focus()` and `blur()` forward to the internal text input.
+glyph), `input`, `hint`, `error`. `focus()`, `blur()`, and `click()` forward to the internal text
+input.
 
 **`editable` — editing a token in place.** Off by default, in which case the token row renders
 exactly as it does without the feature and stays non-focusable. Turn it on and each token becomes a
@@ -2285,6 +2677,17 @@ inline to `--lr-size-8rem`), `--lr-token-input-min-input-inline-size` (default `
 floor that input keeps once tokens have consumed the row), and `--lr-token-input-editor-inline-size`
 (default `--lr-size-6rem`, the inline size of the inline token editor opened by `editable`).
 
+**Additional API surface:**
+
+- `--lr-token-input-token-padding` — Per-token chip padding, scaled by `size`.
+- `--lr-token-input-gap` — Gap between form/row children. Default: `var(--lr-space-xs)`.
+- `--lr-token-input-token-gap` — Gap inside token chips. Default: `var(--lr-space-2xs)`.
+- `--lr-token-input-radius` — Row/token corner radius. Default: `var(--lr-radius)`.
+- `--lr-token-input-token-bg` — Token chip background. Default: `var(--lr-color-brand-quiet)`.
+- `--lr-token-input-action-hover-bg` — Edit/remove hover background. Default: `var(--lr-color-brand-quiet)`.
+- `--lr-token-input-focus-border-color` — Focused row border color. Default: `var(--lr-color-brand)`.
+- `--lr-token-input-invalid-border-color` — Invalid row border color. Default: `var(--lr-color-danger)`.
+
 ## `lr-code-editor`
 
 Dependency-free, form-associated multiline code editor built around a native textarea, with an
@@ -2346,6 +2749,11 @@ spaces — the Tab key keeps inserting `tabSize` spaces in that case.
 - The host gets a `data-invalid` attribute once the field has been blurred at least once and
   validity fails; the styles hang the danger border off it.
 
+**Additional API surface:**
+
+- `selectionDirection` — The current selection direction of the internal editing surface. Type: `'forward' | 'backward' | 'none'`.
+- `click()` — Activates the internal editing surface.
+
 ## `lr-color-picker`
 
 A form-associated native color picker with label, hint, and error chrome. **Properties:** the shared
@@ -2362,6 +2770,13 @@ parts:** `form-control`, `form-control-label` (the label; `label` is an alias ke
 auto-swapped per `size` tier (default `'m'` reads `2.5rem`, `'2xs'` reads `1.25rem`, etc.), matching
 the size ladder `lr-input` uses.
 
+**Additional API surface:**
+
+- `click()` — Activates the internal color input.
+- `--lr-color-picker-gap` — Gap between field chrome. Default: `var(--lr-space-xs)`.
+- `--lr-color-picker-radius` — Swatch corner radius. Default: `var(--lr-radius)`.
+- `--lr-color-picker-hover-border-color` — Hover border color. Default: `var(--lr-color-brand)`.
+
 ## `lr-emoji-picker`
 
 A searchable, keyboard-navigable, form-associated emoji picker. `groups` is fully consumer-suppliable
@@ -2391,8 +2806,10 @@ supporting text rendered below the search/grid; unset renders no hint chrome. `e
 `error` content when provided); unset renders no error chrome. `size: '2xs' | 'xs' | 's' | 'm' | 'l' | 'xl' = 'm'` —
 visual size; scales the emoji grid item box and its glyph proportionally, floored at 24px (WCAG 2.5.8).
 
-**Events:** `lr-change` with `detail: { emoji }` (an emoji was picked — click, or Enter/Space on
-the active grid cell; also sets `value`), plus the shared form `input`, `change`, `focus`, and `blur`.
+**Events:** a pick emits native-style composed `input`, then `change` (both with no detail), then
+`lr-change` with `detail: { emoji }` (click, or Enter/Space on the active grid cell; also sets
+`value`). The internal search input's `focus` and `blur` are re-dispatched as bubbling, composed
+host events. Programmatic `value` changes are silent.
 
 **Keyboard:** the grid is a roving-tabindex listbox (a single Tab stop — only the active emoji is
 tabbable). ArrowLeft/ArrowRight step the active item backward/forward following reading direction
@@ -2451,6 +2868,13 @@ windowed row are additionally capped at 20 regardless of available width.
 supply `groups` directly instead. The loader never throws; a missing or failed peer logs one
 `console.warn` and simply leaves `groups` empty.
 
+**Additional API surface:**
+
+- `--lr-emoji-picker-control-gap` — Gap between field sections. Default: `var(--lr-space-xs)`.
+- `--lr-emoji-picker-radius` — Outer picker corner radius. Default: `var(--lr-radius)`.
+- `--lr-emoji-picker-item-radius` — Search and emoji corner radius. Default: `var(--lr-radius-xs)`.
+- `--lr-emoji-picker-search-hover-border-color` — Search hover border. Default: `var(--lr-color-brand)`.
+
 ## `lr-rubric-form`
 
 A configurable annotation rubric (LangSmith annotation-queue style): score, category, and
@@ -2460,7 +2884,10 @@ freeform-comment keys with a submit-and-next flow for working through an eval qu
 renders `<lr-textarea>`.
 
 **Properties:** `keys: RubricKey[] = []` (attribute: false, each `{ key, type, label?, description?,
-required?, min?, max?, step? }`), `value: RubricValue = {}` (attribute: false), `itemId: string = ''`
+required?, min?, max?, step?, options?, multiple?, placeholder? }`; `options?` contains
+`RubricKeyOption { value: string; label?: string; description?: string }`, `multiple?` selects the
+checkbox-group category route, and `placeholder?` customizes comment input), `value: RubricValue =
+{}` (attribute: false), `itemId: string = ''`
 (attribute `item-id`, reflected), `hasNext: boolean = false` (attribute `has-next`), `skippable:
 boolean = false`, and the shared form properties `name` and `disabled`. `errors: Record<string,
 string>` is the current per-key validation-message state.
@@ -2561,6 +2988,15 @@ peer warning duplication; `lr-flag` itself already logs one) when the optional
 - arrow-key navigation is vertical-only (Home/End/ArrowUp/ArrowDown); there is no
   ArrowLeft/ArrowRight remap under RTL, since there is no horizontal axis to remap.
 
+**Additional API surface:**
+
+- `--lr-locale-picker-gap` — Trigger and option child gap. Default: `var(--lr-space-xs)`.
+- `--lr-locale-picker-radius` — Trigger/listbox/option corner radius. Default: `var(--lr-radius)`.
+- `--lr-locale-picker-trigger-hover-bg` — Trigger hover background. Default: `var(--lr-color-brand-quiet)`.
+- `--lr-locale-picker-open-border-color` — Open trigger border color. Default: `var(--lr-color-brand)`.
+- `--lr-locale-picker-option-selected-border-color` — Selected option border. Default: `var(--lr-color-brand)`.
+- `--lr-locale-picker-option-selected-color` — Selected option text. Default: `var(--lr-color-brand)`.
+
 # Data display, dashboards & flow canvas (`components/data/`)
 
 ## `lr-sparkline`
@@ -2622,7 +3058,8 @@ KPI/stat card — value + unit + label + optional icon/trend/caption.
 - `unit: string = ''`
 - `href?: string` — when it resolves to a safe URL, the root is a real whole-stat `<a>`; unsafe
   URL schemes keep the stat non-interactive
-- `target?: string` / `rel?: string` — forwarded to the anchor while `href` is active
+- `target?: string` — forwarded to the anchor while `href` is active; a nonempty target derives
+  `rel="noopener noreferrer"` rather than exposing a separately settable `rel`
 - `variant: 'neutral'|'success'|'warning'|'danger' = 'neutral'` (reflected)
 - `trend: number = NaN` (a `NaN` sentinel hides the trend pill entirely — set an actual number to
   show it)
@@ -2714,7 +3151,10 @@ drives `emphasis`'s accent edge and value tint).
 
 ## `lr-table`
 
-Sort/select-aware data table. Sorting remains consumer-controlled; optional filtering, pagination,
+Sort/select-aware data table. Sorting is built in and client-side by default (`sortMode="client"`
+orders `rows` from `sortKey`/`sortDir` and the active column's `sortValue`); `sortMode="server"`
+renders `rows` in the order given for a server-ordered table, and `lr-sort` fires on header
+activation either way. Optional filtering, pagination,
 and loading chrome are built in while remaining controlled at the public API boundary. A
 `columns[].heatValue`-opted-in heat-tint mode paints a shared, normalized color-mix background across
 every tinted cell (auto-derived domain, or overridden via `heatTintScale`); `rowTotal`/`grandTotal`
@@ -2724,8 +3164,16 @@ own "consumer computes/renders" contract rather than assuming addition.
 
 **Properties:**
 - `columns: TableColumn<T>[] = []` (attribute: false) — `{ key, label, headerCell?, width?,
-  minWidth?, maxWidth?, resizable?, sortable?, align?: 'start'|'end', priority?: 'medium'|'low', sticky?: boolean |
+  minWidth?, maxWidth?, resizable?, sortable?, sortValue?, align?: 'start'|'end', priority?: 'medium'|'low', sticky?: boolean |
   'start' | 'end', footer?, cellStyle?, heatValue?, cell: (row) => unknown }` —
+  `sortValue(row) => string | number | null | undefined` supplies the comparable value backing
+  client-mode sorting for that column: a finite number sorts numerically, a string sorts through an
+  `Intl.Collator` built from the component's effective locale with `numeric: true` (so `item2`
+  precedes `item10`), and `null`/`undefined`/non-finite sorts **last in both directions** so
+  flipping `sortDir` never floats a block of blanks to the top. Omit it and the column sorts by its
+  stringified `cell()` output instead — meaningful only when `cell()` returns a string or number, so
+  define `sortValue` whenever `cell()` returns a template or element. Ignored under
+  `sortMode="server"` and on a column that is not `sortable`;
   `priority` progressively hides that column via a `@container` query as `[part='base']` narrows
   (`'low'` hides first, under a ~900px container width; `'medium'` next, under ~640px; both
   breakpoints are fixed in `table.styles.ts`, not themeable tokens), reversible via
@@ -2798,6 +3246,19 @@ own "consumer computes/renders" contract rather than assuming addition.
   the two consequences of the fixed algorithm worth knowing before opting in
 - `sortKey: string = ''` (attribute `sort-key`)
 - `sortDir: 'asc'|'desc' = 'asc'` (attribute `sort-dir`)
+- `sortMode: 'client'|'server' = 'client'` (attribute `sort-mode`, reflected) — mirrors
+  `paginationMode`'s identical split. `'client'` (the default) orders `rows` in the browser from
+  `sortKey`/`sortDir` and the active column's `sortValue`; `'server'` renders `rows` exactly as
+  given, for a table whose ordering already happened server-side. `lr-sort` is emitted on header
+  activation under both modes. With no `sortKey` set (the default) `'client'` is a **no-op** — the
+  input order is preserved verbatim — so a table that never sorts renders identically either way.
+  Sorting applies to the whole filtered set *before* client pagination slices the page, so page 1
+  holds the globally-smallest rows rather than a re-sorted slice
+- `defaultSortDir: 'asc'|'desc' = 'asc'` (attribute `default-sort-dir`) — the direction applied
+  whenever header activation switches sorting to a **different** column, including the first column
+  ever sorted. Re-activating the column that is already `sortKey` toggles between `'asc'` and
+  `'desc'` instead, so `defaultSortDir` never overrides a direction the user just chose for the
+  column they are still on. Set `'desc'` for a most-recent-first or highest-first table
 - `rowKey?: (row: T) => string | number` (attribute: false) — derives each row's stable identity for
   DOM-reconciliation and the delegated row click/keydown lookup; falls back to the row's array index
   when omitted, which is only safe while `rows` never reorders — set it whenever `rows` can be
@@ -2844,7 +3305,13 @@ own "consumer computes/renders" contract rather than assuming addition.
   mode slices rows; server mode renders the supplied page unchanged
 - Editable columns emit `lr-cell-edit` on commit and never mutate the supplied row object.
 - `groupBy?: (row: T) => string | number` (attribute: false) — inserts a non-focusable full-width
-  group row before each group
+  group row wherever this key changes between consecutive rendered rows. Supply `rows` with each
+  group already contiguous; the table renders the groups in their first-appearance order in `rows`
+  and never reorders them. A client-mode sort is applied **within** each group, so sorting a
+  grouped table on a column unrelated to the group key reorders rows inside their groups and
+  leaves the grouping intact. The one exception: when the sorted column's value is constant inside
+  every group — the group column itself, most obviously — there is nothing to reorder within a
+  group, so the **groups** are ordered by that value instead.
 - `groupLabel?: (key: string | number, rows: T[]) => unknown` (attribute: false) — custom group
   header content; without it, the group key is rendered as text
 - `expandedContent?: (row: T) => unknown` (attribute: false) — enables a leading expand toggle and
@@ -2871,6 +3338,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
@@ -2885,7 +3355,8 @@ own "consumer computes/renders" contract rather than assuming addition.
   column × footer row). Only rendered when both `rowTotal` is set **and** at least one column defines
   `footer` — otherwise there is no footer row for it to occupy, and this renders nothing
 
-**Events:** `lr-sort` (`detail: { key }`, fired on sortable-header activation), `lr-row-click`
+**Events:** `lr-sort` (`detail: { key }`, fired on sortable-header activation — which also updates
+`sortKey`/`sortDir` itself, per `defaultSortDir` above), `lr-row-click`
 (`detail: { row }`), `lr-load-more` (fired on the "load more" button), `lr-columns-hidden-change`
 (`detail: { hidden: boolean }`, fired only on a real `columnsHidden` transition),
 `lr-columns-revealed` (`detail: { revealed: boolean }`), and `lr-row-expand-toggle`
@@ -2939,6 +3410,14 @@ 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-row-stripe-bg` (default `transparent`) — the background of alternating body rows. The
+component marks the alternating rows itself, so this works without an invalid `::part(row)` attribute
+or structural-pseudo-class selector and does not affect group, expanded, hover, or selected rows.
+`--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).
@@ -2946,12 +3425,13 @@ so multiple `sticky` columns stack instead of overlapping; it is a read-out, not
 **Optional peer deps:** none.
 
 ```html
-<lr-table id="t" sort-key="name" sort-dir="asc"></lr-table>
+<lr-table id="t" sort-key="name" sort-dir="asc" accessible-label="Items"></lr-table>
 <script type="module">
   const t = document.getElementById('t');
   t.columns = [
     { key: 'name', label: 'Name', sortable: true, cell: (r) => r.name },
-    { key: 'value', label: 'Value', align: 'end', cell: (r) => r.value },
+    // sortValue keeps the numeric column comparing as numbers, not as strings.
+    { key: 'value', label: 'Value', align: 'end', sortable: true, sortValue: (r) => r.value, cell: (r) => r.value },
   ];
   t.rows = [{ name: 'Alpha', value: 1 }, { name: 'Beta', value: 2 }];
   t.rowKey = (r) => r.name;
@@ -2961,14 +3441,36 @@ so multiple `sticky` columns stack instead of overlapping; it is a read-out, not
 ```
 
 **Known gotchas:**
+- activating a sortable header now writes `sortKey`/`sortDir` on the table itself, in **both** sort
+  modes — it is no longer a pure `lr-sort` notification. A `sortMode="server"` consumer that
+  re-sorts on `lr-sort` and pushes fresh `rows` back in is unaffected (the table renders whatever
+  order it is handed), but a consumer implementing a *tri-state* header (asc → desc → unsorted) must
+  drive `sortKey`/`sortDir` from its own `lr-sort` handler, since the built-in activation only
+  toggles between the two directions.
+- `sortValue`/`cell` are read off the column object by identity. Mutating a column **in place**
+  (`t.columns[0].sortValue = …`) neither re-renders nor re-sorts; assign a new `columns` array.
+- `groupBy` + client sorting are **not** in conflict: the sort runs per group, not across the whole
+  set, so group rows stay contiguous. The consequence is that the group order is normally yours to
+  control — it follows first appearance in `rows`. The single exception is a sort on a column whose
+  value is constant inside every group (the group column itself, a column functionally determined
+  by the group key, or any column at all when every group holds one row): the within-group sort
+  would be a provable no-op, so the groups are ordered by that constant value instead. That is what
+  keeps `aria-sort` and the header chevron honest — otherwise clicking the group column would flip
+  both while changing nothing. To force a group order in any other case, sort `rows` into it before
+  assigning them (or set `sort-mode="server"` and own the whole ordering).
 - 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 in development builds only — an unnamed grid is an accessibility
+  defect that otherwise renders silently. Production and unknown/unbundled runtimes do not log it.
 - 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
@@ -3091,6 +3593,11 @@ spacing, border, radius, disabled-opacity, and focus-ring tokens.
 - below a 20rem container allocation the summary and controls stack; the breakpoint responds to
   the component's own inline size, not the viewport. Previous/next icons also mirror under RTL
 
+**Additional API surface:**
+
+- `click()` — Forward host activation to the primary editable page control.
+- `--lr-pagination-control-radius` — Border radius of navigation buttons and the page input. Default: `var(--lr-radius)`.
+
 ---
 
 ## `lr-gauge`
@@ -3179,6 +3686,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 +3705,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`,
@@ -3607,9 +4120,13 @@ deeply-nested node's own shadow root still reaches it).
 
 **Properties:**
 - `data: TreeItem[] = []` (attribute: false) — `TreeItem { id: string; label: string; children?:
-  TreeItem[]; badge?: string | number; icon?: unknown; description?: string; accessibleLabel?:
-  string }`; `icon` renders as a decorative leading visual, `description` as secondary visible row
-  text, and `accessibleLabel` names the `role="treeitem"` host without changing its visible label
+  TreeItem[]; selected?: boolean; disabled?: boolean; badge?: string | number; badges?: TreeBadge[];
+  icon?: unknown; description?: string; accessibleLabel?: string }`. `TreeBadge` is `{ text:
+  string; tone?: TreeBadgeTone; label?: string }`, where `TreeBadgeTone` is
+  `'neutral'|'brand'|'success'|'warning'|'danger'`. The legacy singular `badge` renders first;
+  `badges` adds tone-mapped chips after it and each chip's accessible name uses `label ?? text`.
+  `icon` renders as a decorative leading visual, `description` as secondary visible row text, and
+  `accessibleLabel` names the `role="treeitem"` host without changing its visible label
 - `label: string = ''` — accessible name for the tree; `role="tree"` lives on an internal
   `[part="base"]` element. The component forwards a host `aria-label` to that semantic element when
   `label` is empty; `label` takes precedence when both are set. External `aria-labelledby` idrefs
@@ -3685,9 +4202,11 @@ through `lr-tree`'s light DOM.
 
 **Slots:** none.
 
-**CSS parts:** `row`, `toggle`, `icon`, `content`, `label`, `description`, `badge`, `group`. `icon` is
-`aria-hidden="true"`; `content` groups the primary label and optional wrapping secondary
-description while preserving one interactive treeitem per row.
+**CSS parts:** `row`, `toggle`, `icon`, `content`, `label`, `description`, `badge`, `group`. `badge`
+is applied to the legacy singular badge and to every `badges` chip; additive chips carry
+`data-tone="neutral|brand|success|warning|danger"`. `icon` is `aria-hidden="true"`; `content`
+groups the primary label and optional wrapping secondary description while preserving one
+interactive treeitem per row.
 
 **Themeable custom properties:** `--lr-tree-depth` (internal, set inline per row for
 indentation), plus the shared tokens listed above.
@@ -3728,6 +4247,12 @@ indentation), plus the shared tokens listed above.
 - `lr-file-tree` does **not** forward `reorderable`, and deliberately so: its `TreeItem[]` is derived
   from `nodes` on every render and keyed by filesystem path, an order it does not own.
 
+**Additional API surface:**
+
+- `--lr-tree-selected-color` — Selected-node text color.
+- `--lr-tree-selected-bg` — Selected-node background.
+- `ancestry` — Ancestor object identities used to stop cyclic caller graphs before recursive rendering. Type: `TreeItem[]`.
+
 ---
 
 ## `lr-flow-canvas`
@@ -3755,8 +4280,10 @@ controlled-component contract.
   `lr-node-palette` drag sets, emitting `lr-node-add`
 - `locked: boolean = false` (reflected) — freezes pan/zoom/drag/connect without touching the other
   gesture flags
-- `selectedNodeIds: string[] = []`, `selectedEdgeIds: string[] = []` (attribute: false) — controlled;
-  the host assigns these back from `lr-selection-change`
+- `selectedNodeIds: string[] = []`, `selectedEdgeIds: string[] = []` (attribute: false) — seed or
+  replace selection state. Node/edge activation and clear-selection gestures also update these
+  arrays internally before emitting `lr-selection-change`; a host may assign its own authoritative
+  state back.
 - `minZoom: number = 0.25` (attribute `min-zoom`), `maxZoom: number = 2` (attribute `max-zoom`)
 - `grid: number = 8` — snap step in content px for drags/nudges/drop positions (`0` disables
   snapping); also the dotted background's base spacing
@@ -3835,9 +4362,10 @@ treatment entirely.
 ```
 
 **Known gotchas:**
-- Fully controlled: `nodes`/`edges`/`selectedNodeIds`/`selectedEdgeIds` are never mutated
-  internally — `lr-node-move`, `lr-selection-change`, `lr-connect`, `lr-node-add`, and
-  `lr-selection-delete` are all requests the host applies back, same contract as `lr-table`.
+- `nodes` and `edges` are controlled inputs: move, connect, add, and delete events are requests the
+  host applies back. Selection is hybrid state: `selectedNodeIds`/`selectedEdgeIds` accept external
+  replacement, while node/edge activation and clear-selection gestures update them internally and
+  emit `lr-selection-change`.
 - Auto-layout (via the dependency-free `layeredLayout()` util) only ever positions nodes that are
   missing an explicit `position`; a node the host has already positioned is left exactly where it is
   and used as a fixed anchor for the rest of the layout pass.
@@ -3848,6 +4376,12 @@ treatment entirely.
   deltas are mirrored so content still visually follows the cursor, matching every other
   RTL-mirrored surface in this library.
 
+**Additional API surface:**
+
+- `part="edge-hit-area"` — The transparent wide pointer target behind an edge.
+- `part="node-control"` — The visually hidden, roving selection button for a node.
+- `--lr-flow-canvas-node-selected-outline-color` — Outline color of a selected node. Default: `var(--lr-flow-canvas-node-current-outline-color,var(--lr-color-brand))`.
+
 ---
 
 ## `lr-flow-node`
@@ -3927,8 +4461,8 @@ disagree.
 **Properties:**
 - `for: string = ''` — id of the target `lr-flow-canvas`; when empty, the nearest ancestor canvas
   is used (the slotted-into-a-corner-slot case, the primary wiring)
-- `label: string = ''` — accessible name for the map region; falls back to a host `aria-label`, then
-  a localized default
+- `label: string = ''` — accessible name for the map region. A host `aria-label` takes precedence,
+  followed by `label`, then the localized default
 
 **Events:** none.
 
@@ -3955,6 +4489,11 @@ draggable, focusable view rectangle).
 - Dragging the viewport rectangle calls the canvas's `setViewport()` directly; there's no separate
   event to wire up.
 
+**Additional API surface:**
+
+- `part="instructions"` — Visually hidden keyboard instructions for the viewport.
+- `part="live-region"` — Visually hidden viewport-change announcements.
+
 ---
 
 ## `lr-flow-controls`
@@ -4106,10 +4645,12 @@ capacity), `segment` (one occupied segment — carries `data-tone` and, for cust
 <lr-context-meter variant="ring" total="128000" .segments=${segments}></lr-context-meter>
 ```
 
-`role="img"` and a computed `aria-label` are set imperatively on the *host* element itself in
-`willUpdate` (mirroring `lr-gauge`'s "meter" role convention) — every internal node (`track`,
-`segment`, the ring's `<svg>`, `label`) is `aria-hidden`, so a screen reader gets one meaningful
-summary string instead of the raw markup. That summary's "used" figure is the sum of
+An internal visually-hidden semantic node carries `role="meter"` plus `aria-valuenow`,
+`aria-valuemin`, and `aria-valuemax` whenever `total > 0`; without a valid positive total it uses
+`role="group"` and omits numeric meter attributes. Its accessible name is the host `aria-label`
+when present, otherwise the generated summary. A separate visually-hidden segment list exposes
+each labeled quantity, while the visible track, segments, ring SVG, and visible label remain
+`aria-hidden`. The summary's "used" figure is the sum of
 `segments[].value`, clamped to `total` whenever `total > 0` so the announced text can never claim
 more than 100% used (e.g. `segments` summing to `150000` against `total="128000"` still announces
 `"128,000 of 128,000 used"`) — matching what the *visual* meter shows, since each segment's ratio is
@@ -4123,8 +4664,8 @@ numbers, so the two circular-meter components in the library share one visual sc
 
 **Known gotchas:**
 - The ring variant's per-segment `<title>` and the bar variant's per-segment `title=` attribute are
-  native mouse-hover tooltips only — they sit inside `aria-hidden` markup, so screen readers never
-  read them; only the host's own `role="img"`/`aria-label` carries accessible information.
+  native mouse-hover tooltips only — they sit inside `aria-hidden` markup. Screen readers use the
+  hidden meter/group summary and segment list instead.
 - `variant="ring"` fixes the host at `8em × 8em` (`:host([variant='ring'])`) — the bar variant's
   `inline-size: 100%` does not apply in ring mode; resize it via `font-size` or an explicit
   width/height override on the host instead.
@@ -4132,6 +4673,12 @@ numbers, so the two circular-meter components in the library share one visual sc
   `segments` render further around the circle (starting at 12 o'clock, going clockwise); there's no
   independent sort/z-order control.
 
+**Additional API surface:**
+
+- `part="segment-item"` — One visually-hidden segment label/count pair.
+- `part="segment-list"` — The visually-hidden list exposing the segment breakdown.
+- `part="semantic"` — The visually-hidden meter/group carrying aggregate range semantics.
+
 ---
 
 ## `lr-calendar`
@@ -4301,13 +4848,28 @@ parts:** `base`, `path-fields`, `start-input`, `end-input`, `relationship-picker
 `saved-queries`, `saved-queries-label`, `saved-list`, `saved-item`, `saved-load-button`,
 `saved-delete-button`, `saved-empty`.
 
+**Additional API surface:**
+
+- `errorText` — Caller-supplied outer error text. Field-level validation remains on the affected controls. Type: `string`.
+- `hint` — Supporting text rendered below the outer label. Type: `string`.
+- `error-text` attribute — Caller-supplied outer error text. Field-level validation remains on the affected controls.
+- `hint` attribute — Supporting text rendered below the outer label.
+- `hint` slot — Supporting text for the complete form control.
+- `part="hint"` — Supporting text for the complete form control.
+
 ## `lr-query-builder`
 
 Composable structured-query builder for tabular or dashboard data: condition rows combined with an
 AND/OR combinator.
 
-**Properties:** `fields`, `value`, `disabled`, `addCondition`, `removeCondition`. **Events:**
-`lr-input`, `lr-add-condition`, `lr-remove-condition`. **CSS parts:** `base`, `conditions`,
+**Properties:** `fields`, `value`, `disabled`.
+
+**Methods:** `addCondition()` appends a condition using the first available field and emits
+`lr-add-condition`; it is a no-op while disabled or when there are no fields.
+`removeCondition(id)` removes the matching condition and emits `lr-remove-condition`; it is a
+no-op while disabled or when the id is absent.
+
+**Events:** `lr-input`, `lr-add-condition`, `lr-remove-condition`. **CSS parts:** `base`, `conditions`,
 `condition`, `field-select`, `operator-select`, `value`, `combinator`, `add-button`,
 `remove-button`, `empty`.
 
@@ -4321,9 +4883,18 @@ 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. Initialization occurs on the first update so framework property bindings committed
+  after connection in the same turn — including `defaultSizes` and `storageKey` — are honored
+  before the layout becomes live. 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).
@@ -4558,15 +5129,20 @@ position) survives the transition.
 - `backdropInset: string = ''` (attribute `backdrop-inset`) — overrides the fullscreen backdrop's
   CSS `inset` independently from `fullscreenInset`; when empty, it follows `fullscreenInset`
 - `views: WidgetView[] = []` (attribute: false) — named alternate views for the panel body, e.g. a
-  chart/table toggle inside the same card chrome; `WidgetView { id: string; label: string; icon?:
-  TemplateResult }`. Each entry gets a header toggle button (`[part='view-toggle']`) and a
-  `<slot name="view-${id}">`. Empty (the default) renders today's single unnamed default slot as the
-  sole view, unchanged.
+  chart/table toggle inside the same card chrome; `WidgetView { id: string; label?: string; icon?:
+  TemplateResult; ariaLabel?: string }`. Each entry gets a header toggle button
+  (`[part='view-toggle']`) and a `<slot name="view-${id}">`. An icon-only view should set
+  `ariaLabel`; if both labels are omitted, the button uses `id` as a last-resort accessible name.
+  Empty (the default) renders today's single unnamed default slot as the sole view, unchanged.
 - `activeView: string = ''` (attribute: false) — the currently active view's `id`; defaults to the
   first entry of `views` (or `''` when `views` is empty). Settable directly to control the active
   view externally; also updated internally when a view toggle is clicked.
-- `accessibleLabel: string = ''` (attribute `aria-label`) — overrides the label-derived fullscreen
-  dialog name.
+- `accessibleLabel: string | null = null` (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 +5205,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 +5215,16 @@ 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.
+
+**Additional API surface:**
+
+- `part="view-icon"` — Decorative icon content inside a view toggle.
+- `part="view-label"` — Visible label text inside a view toggle.
 
 ---
 
@@ -4838,9 +5427,8 @@ before, so rendering is unchanged. Otherwise shared tokens —
 Ordered multi-step wizard/form navigation: an index/label per step, `current`/`completed`/`disabled`/
 `error` state, and click-to-jump. First-party invention (no Web Awesome equivalent). Fully
 data-driven and controlled, like `lr-table`'s `columns`/`rows` — it never mutates `steps` itself; a
-click, or Enter/Space on a non-disabled step, fires a cancelable `lr-step-select`, and the host
-decides whether/how `steps` changes in response (mirroring `lr-dialog-close`'s cancelable-event
-convention).
+click, or Enter/Space on a non-disabled step, fires a non-cancelable `lr-step-select`, and the host
+decides whether/how `steps` changes in response.
 
 **Properties:**
 - `steps: StepItem[] = []` (attribute: false) — `StepItem { id: string; label: string; state:
@@ -4886,19 +5474,20 @@ convention).
   doesn't resolve to a length. Also reflected as `data-effective-orientation` (only present while
   `orientationBreakpoint` resolves to a usable length).
 - `accessibleLabel: string | null = null` (attribute `aria-label`) — accessible name applied to the
-  `role="tablist"` step strip; attribute-reflects from a host-level `aria-label`. Unset, the
-  tablist renders without an `aria-label` (there is no localized default name).
+  `role="list"` step strip; attribute-reflects from a host-level `aria-label`. Unset, the list
+  renders without an `aria-label` (there is no localized default name).
 
 **Events:** `lr-step-select` (`detail: { index, id }`) — fired on click, or Enter/Space while
-focused, on a non-`disabled` step. Cancelable, though this component takes no default action of its
-own to prevent (it never mutates `steps`) — `preventDefault()` is available for a host that wants a
-single place to short-circuit its own listener's follow-up work. `lr-stepper-orientation-change`
+focused, on a non-`disabled` step. It is non-cancelable because the component takes no default
+action to veto: it never mutates `steps`. `lr-stepper-orientation-change`
 (`detail: { orientation }`) — fired only when an enabled `orientationBreakpoint` actually changes
 `effectiveOrientation`.
 
 **Slots:** none.
 
-**CSS parts:** `base` (root wrapper, `role="tablist"`), `step` (a single step button, `role="tab"`),
+**CSS parts:** `base` (root wrapper, `role="list"`), `step-item` (the `role="listitem"` wrapper for
+one step), `step` (a single native button; the current step carries `aria-current="step"` and every
+other step carries `aria-current="false"`),
 `step-icon` (optional leading topic glyph from the step's `icon` field; only rendered when the step
 has one, additionally to — never instead of — `step-index`/`step-check`), `step-index` (the numbered
 index chip, shown for `pending`/`current`/`error` steps), `step-check` (the completed-checkmark
@@ -4949,9 +5538,9 @@ each falls back to the token its rule used before. Otherwise shared tokens —
 - there's no built-in "step forward/back" method — advancing the wizard is entirely the host's job:
   react to `lr-step-select` (or its own Next/Back buttons) and reassign `steps` with updated
   `state` values.
-- `role="tablist"`/`role="tab"` back the keyboard/focus contract (roving tabindex, arrow-key
-  navigation) even though this isn't a `<lr-tabs>`-style panel switcher — there's no associated
-  `role="tabpanel"`, since this component renders no panel content of its own.
+- The stepper exposes ordered progress/navigation semantics (`list`/`listitem` plus native step
+  buttons), not tabs: it owns no tab panels. Roving tabindex and orientation-aware arrow-key
+  navigation remain available independently of those semantics.
 - Left/Right (horizontal) and Up/Down (vertical) are mutually exclusive per `orientation` — there's
   no single set of keys that works in both.
 
@@ -5102,6 +5691,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),
@@ -5163,6 +5759,12 @@ Otherwise shared tokens — `--lr-color-border`/`-surface`/`-text`/
 - the semantic `radiogroup` lives inside shadow DOM. Set `label` (preferred for reactive code) or a
   host `aria-label`; the component deliberately forwards the resulting name to that internal role.
 
+**Additional API surface:**
+
+- `--lr-segmented-track-gap` — Gap between segments. Default: `var(--lr-size-0-125rem)`.
+- `--lr-segmented-track-radius` — Track corner radius. Default: `var(--lr-radius)`.
+- `--lr-segmented-track-padding` — Track inset padding. Default: `var(--lr-size-0-125rem)`.
+
 ---
 
 ## `lr-virtual-list`
@@ -5232,7 +5834,7 @@ invention (no Web Awesome equivalent).
 - `overscan: number = 6` — extra rows rendered beyond the visible viewport on each side; finite
   values are floored and clamped to 0–100, while non-finite values use the default 6, so an invalid
   runtime value cannot disable windowing and render the entire collection.
-- `activeId: string = ''` (attribute `active-id`) — when set and it matches a row's `keyFunction`
+- `activeId: string | number | '' = ''` (attribute `active-id`) — when set and it matches a row's `keyFunction`
   result (compared with `Object.is` against the typed value — attribute values arrive as strings, so
   assign the property directly for a numeric key), that row is smoothly scrolled into view whenever
   this changes, and rendered with `aria-current="true"`.
@@ -5408,8 +6010,13 @@ 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 the fields
+selected by `persist` to `localStorage` under `lr-app-rail:${storageKey}` and restore them on the
+next mount (mirrors `lr-split`'s `storage-key`; effective `mode` is breakpoint-derived and never
+persisted). The backward-compatible allowlist is `open width`; use
+`persist="width preferred-mode"` for durable layout preference without restoring the transient
+mobile overlay. 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 +6061,14 @@ 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 the fields selected by
+  `persist` to `localStorage` under `lr-app-rail:${storageKey}` and restores them on the next
+  mount. Effective `mode` is breakpoint-derived and never persisted. Unset means no persistence.
+- `persist: string = 'open width'` — whitespace-separated field allowlist used with `storageKey`.
+  Valid `AppRailPersistField` tokens are `open`, `width` (`railWidthPx`), and `preferred-mode`
+  (`preferredMode`). The default preserves the existing open+width behavior. Use
+  `persist="width preferred-mode"` when overlay-open state is controlled or should stay
+  session-only.
 - `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
@@ -5771,8 +6386,12 @@ returning to the trigger)
 **Slots:** `trigger` (the consumer's own trigger element — first assigned element wins if several
 are assigned; enhanced imperatively with `aria-haspopup="menu"`/`aria-expanded`/`aria-controls`
 since those attributes belong on the actual interactive trigger, which lives outside this
-component's shadow root), default (`<lr-menu-item>` elements, plus optionally plain `<hr>`
-dividers between groups — native `<hr>` already carries an implicit `separator` role),
+component's shadow root. `aria-controls` targets the `lr-menu` host, which receives a stable
+generated id only when the consumer did not provide one, rather than the shadow-private list id.
+`lr-button`/`lr-icon-button` forward the popup/expanded values to their focused shadow-internal
+native control and resolve the controls element-reference across their shadow boundary), default
+(`<lr-menu-item>` elements, plus optionally plain `<hr>` dividers — native `<hr>` already carries
+an implicit `separator` role),
 `header` and `footer` (composed, deliberately non-menu-item content — a filter/search field, a
 section title, an "Apply"/"Done" button, a count — rendered above/below the items inside
 `[part="popup"]` but **outside** the `role="menu"` list. Both collapse to no box at all while
@@ -5954,8 +6573,10 @@ docked case.
 - `collapsible: boolean = false` (reflected)
 - `collapsed: boolean = false` (reflected)
 - `resizable: boolean = true` (reflected) — when `false`, no drag handle renders at all and the panel
-  is a fixed size. (Assign `false` via a **property** binding, e.g. `.resizable=${false}` — a
-  `?resizable=${false}` boolean-attribute binding cannot override a `true` default; see AGENTS.md.)
+  is a fixed size. Its string-aware converter accepts `resizable="false"` as false despite the
+  true default. A Lit property binding (`.resizable=${false}`) also disables it; a false
+  boolean-attribute binding (`?resizable=${false}`) only removes the attribute and cannot override
+  a true-defaulting property.
 
 **Exported helper:** `parseLengthPx(length: string, containerPx: number, fontSizeEl: Element =
 document.documentElement): number | undefined` — resolves an arbitrary CSS length (`px`, `rem`, `em`,
@@ -6047,6 +6668,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**
@@ -6102,6 +6728,11 @@ the `footer` slot, hidden entirely when empty).
   `<lr-button>` retargets to the host, but its composed path still contains the internal native
   `<button>`.
 
+**Additional API surface:**
+
+- `accessibleLabel` — Host `aria-label` forwarded to the native no-href activation button. Type: `string | null`.
+- `part="activation-button"` — The native whole-card action, rendered while `interactive` without `href`. It is a sibling of slotted controls, so actionable descendants are never nested inside another actionable role.
+
 ---
 
 ## `lr-command-palette`
@@ -6154,6 +6785,13 @@ after `::part()`), so highlighting the active row previously required hijacking
 `--lr-color-brand-quiet` token and repainting everything else that read it. Unset, it falls back to
 that token, so rendering is unchanged.
 
+**Additional API surface:**
+
+- `part="command-group"` — A labeled ARIA group containing visible command options.
+- `part="list-spacer"` — Virtual result extent inside the scrolling list.
+- `--lr-command-palette-row-height` — Virtual command-row height. Default: `var(--lr-size-3rem)`.
+- `--lr-command-palette-group-height` — Virtual group-heading height. Default: `var(--lr-size-2rem)`.
+
 ## `lr-details`, `lr-accordion`, and `lr-accordion-item`
 
 `lr-details` is a native-semantics disclosure panel. `lr-accordion` coordinates slotted
@@ -6192,6 +6830,10 @@ set on the item, on `<lr-breadcrumb>`, or on any ancestor above the trail:
 `--lr-color-text-quiet` token and repainting everything else that read it. Unset, it falls back to
 that token.
 
+**Additional API surface:**
+
+- `part="separator"` — Decorative separator shown before non-first items.
+
 ## `lr-dashboard-grid`
 
 Responsive, keyboard-accessible controlled widget grid. It positions layout entries and emits
@@ -6218,6 +6860,10 @@ overriding them from a stylesheet has no effect — set the properties instead.
 preview of its own `:focus-visible` ring, shown because every cell is a real focusable,
 draggable/resizable target; set it to `transparent` to opt out of the hover treatment entirely.
 
+**Additional API surface:**
+
+- `--lr-dashboard-grid-collision-outline-color` — Outline color of a cell whose current drag/resize preview collides with another cell. Default: `var(--lr-color-danger)`.
+
 ## `lr-drilldown-panel`
 
 Controlled navigation shell from a chart or table datum to related evidence, documents, entities,
@@ -6236,10 +6882,25 @@ false), `accessibleLabel: string | null = null` (attribute `aria-label` — name
 
 Dashboard filter row that composes Lyra inputs and removable chips, with reset and loading states.
 
-**Properties:** `filters`, `value`, `disabled`, `loading`, `label`, `hasActiveFilters`,
-`invalidFilterIds`, `checkValidity`, `reportValidity`, `reset`. **Events:** `lr-input`, `lr-reset`,
-`lr-validity-change`. **CSS parts:** `base`, `controls`, `filter-control`, `active-filters`,
-`chips`, `chip`, `reset-button`, `status`.
+**Properties:**
+
+- `filters: FilterBarFilterDefinition[] = []` (attribute: false) — filter schema in render order.
+- `value: FilterBarValue = {}` (attribute: false) — current values keyed by filter id; reads and
+  writes are shallow-copied.
+- `label: string = ''` — accessible name for the internal `role="group"`.
+- `disabled: boolean = false` (reflected) — disables every filter control and reset action.
+- `loading: boolean = false` (reflected) — shows the status spinner and disables reset while leaving
+  filters editable.
+- `hasActiveFilters: boolean` (read-only) — whether any configured filter currently has a value.
+- `invalidFilterIds: string[]` (read-only) — ids of required filters whose values are unset.
+
+**Methods:** `checkValidity(): boolean` returns whether every required filter is set without
+revealing errors; `reportValidity(): boolean` returns the same state and reveals every current
+required-field error; `reset(): void` restores each definition's `defaultValue` (or unsets it),
+unless the bar is disabled.
+
+**Events:** `lr-input`, `lr-reset`, `lr-validity-change`. **CSS parts:** `base`, `controls`,
+`filter-control`, `active-filters`, `chips`, `chip`, `reset-button`, `status`.
 
 Each filter definition's `type` selects which existing Lyra input renders it — this component
 composes them and never invents a control of its own. `'select'`/`'combobox'` map to their
@@ -6314,8 +6975,8 @@ DOM.
 
 **Themeable custom properties:** `--lr-toast-accent-width` (4px),
 `--lr-toast-show-duration`/`--lr-toast-hide-duration`
-(`var(--lr-transition-base, 180ms ease-out)` — 180ms by default, matching the JS-side show/hide
-animation timer, which is not itself reading this token), `--lr-toast-padding`
+(`var(--lr-transition-base, 180ms ease-out)` — the show/hide lifecycle reads the resolved computed
+transition duration and uses it for its completion fallback), `--lr-toast-padding`
 (`var(--lr-space-m)`), `--lr-toast-font-size` (`1rem`) — both are auto-swapped per `size`, from a
 compact `xs` up to a roomier `xl` — `--lr-toast-accent-color` (defaults to `--lr-color-border`,
 auto-swapped per `variant` to `--lr-color-brand/-success/-warning/-danger`).
@@ -6338,7 +6999,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,16 +7014,14 @@ 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>
 ```
 
 **Known gotchas:**
-- possible nested live-region double-announcement: the stack region is
-  `role="status" aria-live="polite"` **and** each `lr-toast-item` independently self-assigns its
-  own `role` (`status`/`alert`) — nesting live regions can cause some screen readers to announce a
-  new toast twice. Plausible from the code, unverified against real AT.
+- the stack itself has no live-region role; each `lr-toast-item` owns the single `status`/`alert`
+  role appropriate to its current variant, avoiding nested live-region announcements.
 - the close button's accessible name is derived from the toast's own message text (`"Close: <first
   40 chars>…"`, falling back to bare `"Close"` only when the toast has no text content) rather than
   a bare `"Close"` on every instance — useful when several toasts are stacked and a screen-reader or
@@ -6401,7 +7060,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.
@@ -6696,16 +7357,13 @@ already follow.
   whole pill using a loud-color-on-quiet-tint convention; `neutral` has no dedicated token pair, so
   it falls back to a plain bordered-surface look)
 - `removable: boolean = false` (reflected — shows the remove (×) button)
-- `selected: boolean = false` (reflected) — opt-in toggle/pressed mode: when set, `[part='base']`
-  itself becomes focusable and keyboard-activatable (Enter/Space, mirroring native `<button>`
-  behavior), reflects `aria-pressed` (explicitly `"false"`, not omitted, whenever toggle mode is
-  active but unpressed), and toggles on click/activation, emitting `lr-chip-select`.
-  Has no effect (no interactive semantics added to `[part='base']`) when combined with `removable`,
-  since the remove button already nests inside `[part='base']` — a focusable descendant of a
-  `role="button"` ancestor isn't allowed there, and this component's two real use cases (a
-  chart-series visibility toggle, a category filter chip) never need both at once. `false` (the
-  default, with `toggleable` also left at its default) reproduces the exact passive-label-pill
-  output.
+- `selected: boolean = false` (reflected) — current value for opt-in toggle/pressed mode. Once
+  toggle mode is active, a separate native `[part='toggle-button']` owns focus, Enter/Space/click
+  activation, and explicit `"true"`/`"false"` `aria-pressed`; `[part='base']` remains a container
+  and the default-slot label is inert. Activation proposes the opposite value through the
+  cancelable `lr-chip-select` event and mutates `selected` only when that event is not prevented.
+  Has no toggle effect when combined with `removable`, where the remove button is the sole control.
+  `false` (with `toggleable` also left at its default) reproduces the passive label-pill output.
 - `toggleable: boolean = false` (reflected) — explicit opt-in into `selected`'s toggle/pressed
   interactive mode, independent of `selected`'s own current value. Setting `selected` to `true` at
   any point opts in automatically and keeps `toggleable` `true` from then on (enough for a chip that
@@ -6718,16 +7376,21 @@ already follow.
 
 **Events:** `lr-remove` (`detail: { value }` — the remove (×) button was activated via click or
 Enter/Space while focused; only rendered/reachable while `removable`), `lr-chip-select`
-(`detail: { value, selected }` — fired on click, or Enter/Space while focused, when `selected` mode
-is active and `removable` is not set; the chip has already toggled its own `selected` state by the
-time this fires)
+(`detail: { value, selected }` — cancelable; fired from the native toggle button on click or
+Enter/Space with the proposed next state when toggle mode is active and `removable` is not set.
+Calling `preventDefault()` keeps the current `selected` state unchanged)
+
+**Methods:** `focus(options?)`, `blur()`, and `click()` forward to the active internal control
+(toggle or remove button); a passive chip's `click()` retains ordinary host behavior.
 
-**Slots:** default (the chip's label content), `icon` (optional leading icon or status dot; nothing
-reserved for it — no extra gap — when left empty)
+**Slots:** default (the chip's label content; inert in toggle mode, so move links/buttons outside a
+toggleable chip), `icon` (optional leading icon or status dot; nothing reserved for it — no extra
+gap — when left empty)
 
 **CSS parts:** `base` (the pill's root container), `icon` (wrapper around the `icon` slot; hidden
-entirely while empty), `label` (wrapper around the default slot), `remove-button` (the remove (×)
-affordance, only rendered while `removable`)
+entirely while empty), `label` (non-interactive wrapper around the default slot), `toggle-button`
+(the real native toggle control, rendered over the label in toggle mode), `remove-button` (the
+remove (×) affordance, only rendered while `removable`)
 
 **Themeable custom properties:** `--lr-chip-accent`, `--lr-chip-bg`, `--lr-chip-border`
 (component-local trio swapped per `tone` rather than repeating background/color/border per part per
@@ -6859,11 +7522,13 @@ string. First-party invention (no Web Awesome equivalent).
   (single letters/digits upper-cased).
 
 **Exported types/functions (also directly usable standalone):** `KbdKeyLabel { visual: string;
-word: string }` — one resolved token's rendered glyph and spelled-out word.
-`shortcutTokenLabel(rawToken: string, isMac: boolean): KbdKeyLabel` — resolves a single token,
-parameterized on `isMac` so both platform branches are unit-testable without spoofing `navigator`.
-`parseShortcut(keys: string, isMac: boolean): KbdKeyLabel[]` — splits and resolves a full `keys`
-string.
+word: string }` — one resolved token's rendered glyph and spelled-out word; `KbdLocalize = (key:
+string, fallback: string) => string`.
+`shortcutTokenLabel(rawToken: string, isMac: boolean, localize?: KbdLocalize): KbdKeyLabel`
+resolves a single token, parameterized on `isMac` so both platform branches are unit-testable
+without spoofing `navigator`; the optional callback localizes spoken key names.
+`parseShortcut(keys: string, isMac: boolean, localize?: KbdLocalize): KbdKeyLabel[]` splits and
+resolves a full `keys` string with the same optional localization callback.
 
 **Events:** none — purely presentational.
 
@@ -6918,6 +7583,11 @@ 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: false }` to opt out of focus restoration. By default, `hide()`, Escape, light
+dismiss, and a bare `el.open = false` all return focus to the slotted trigger, or to a virtual
+anchor's explicit `returnFocusTo`; a virtual anchor with no return target closes without moving
+focus. 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).
@@ -7002,6 +7672,12 @@ The rendered progressbar exposes `aria-valuemin`, `aria-valuemax`, and `aria-val
 determinate.
 
 **Slots:** `label`. **CSS parts:** `base`, `track`, `indicator`, `label`.
+**Themeable custom properties:** `--lr-progress-height` (default `var(--lr-size-0-5rem)`) — the
+block size of the progress track.
+
+**Additional API surface:**
+
+- `--lr-progress-duration` — Indeterminate sweep timing. Default: `var(--lr-transition-ambient)`.
 
 ## `lr-progress-ring`
 
@@ -7082,6 +7758,12 @@ inside each star, clipped to the fractional `precision` value). **Themeable cust
 (default `--lr-color-border` — unfilled-star color), and `--lr-rating-size` (default
 `--lr-font-size-xl` — star size).
 
+**Additional API surface:**
+
+- `blur()` — Forwards host blur to the internal rating control.
+- `click()` — Forwards host activation to the internal rating control.
+- `focus()` — Forwards host focus to the internal rating control.
+
 # Utilities, formatting & observers (`components/utility/`)
 
 ## `lr-export-button`
@@ -7112,12 +7794,14 @@ immediately) or multi-format (click opens a small menu).
   name and feeds the localized format-menu name without changing the visible label
 - `open: boolean = false` (reflected)
 
-**Methods:** `focus(options?)` and `blur()` forward to the native trigger button.
+**Methods:** `focus(options?)`, `blur()`, and `click()` forward to the native trigger button.
 
 **Events:** `lr-export` (`detail: { format: string }`, **cancelable** — call `preventDefault()` to
 substitute your own server-generated download instead of the built-in client-side one),
 `lr-export-complete` (`detail: { format: 'csv' | 'json' }`, fires only after a non-cancelled
-built-in download completes), `lr-show`, `lr-hide` (format-menu visibility transitions)
+built-in download completes), `lr-export-error` (`detail: { format: 'csv' | 'json', error:
+unknown }`, fires when a built-in export cannot be serialized or downloaded; activation does not
+throw into consumer code), `lr-show`, `lr-hide` (format-menu visibility transitions)
 
 **Slots:** none.
 
@@ -7219,6 +7903,10 @@ buttons, this has no code/JSON content model to adopt just to reuse the copy aff
   and some engines throw synchronously rather than rejecting — either way `lr-copy` still fires
   with the intended text so a consumer can always show its own confirmation/fallback UI.
 
+**Additional API surface:**
+
+- `click()` — Activates the native button, matching the host focus/blur forwarding contract.
+
 ---
 
 ## `lr-resize-observer`
@@ -7289,8 +7977,10 @@ stack overflow on cyclic `data`.
 **Methods:** `runSearch(query)` sets the declarative `search` property and awaits the recompute,
 resolving the match count — named distinctly from `search` because a class member can't share a name
 with a reactive property. `searchNext()`/`searchPrevious()` advance/step back a match cursor
-(wrapping) and scroll the active match into view, resolving `false` when there are no matches.
-`clearSearch()` resets `search` to `''`, clearing all matches and the cursor.
+(wrapping), reveal that selected match even when one of its ancestors was explicitly collapsed,
+mark it as the active `aria-current` result, announce its position, and scroll it into view;
+they resolve `false` when there are no matches. `clearSearch()` resets `search` to `''`, clearing all
+matches and the cursor.
 
 **Events:** `lr-copy` (`detail: { text: string }`) — fired by the top-level copy button or a
 per-node one. Fires even when `navigator.clipboard` is unavailable or the write silently failed
@@ -7321,7 +8011,13 @@ until `max-height` is set), `--lr-json-viewer-font` (default `var(--lr-font-mono
 `--lr-json-viewer-match-bg` (default `var(--lr-color-warning-quiet)`) — background, and surrounding
 box-shadow, of a key/value that currently matches `search`. Component-scoped indirection over the
 shared `--lr-color-warning-quiet` token, so a consumer can retheme just this search-match highlight
-without repainting every other warning-toned surface that reads the same shared token. Plus shared
+without repainting every other warning-toned surface that reads the same shared token;
+`--lr-json-viewer-active-outline` (default `var(--lr-focus-ring-color)`) — outline color for the
+current imperative search match; `--lr-json-viewer-string-color` (default
+`var(--lr-color-success)`), `--lr-json-viewer-number-color` (default `var(--lr-color-brand)`),
+`--lr-json-viewer-boolean-color` (default `var(--lr-color-warning)`), and
+`--lr-json-viewer-null-color` (default `var(--lr-color-text-quiet)`) — per-value-type color hooks.
+Plus shared
 tokens `--lr-color-border/-surface/-text/-text-quiet/-brand/-brand-quiet/-success/-warning/-warning-quiet`,
 `--lr-radius`, `--lr-space-xs/-s/-l`, `--lr-focus-ring-width/-color/-offset`,
 `--lr-transition-fast`.
@@ -7347,9 +8043,11 @@ html`<lr-json-viewer .data=${apiResponse} copyable max-height="24rem" search=${q
   binding, never as a plain HTML attribute.
 - Search highlighting auto-expands only the *ancestors* of a match, not the whole tree — a
   non-matching sibling subtree elsewhere stays collapsed (or expanded) exactly as it already was.
-- An explicit per-node expand/collapse (from clicking a node's `toggle` button) permanently overrides
-  both `collapsedDepth` and any search-driven auto-expand for that path, until `data` is reassigned
-  with a different shape.
+- An explicit per-node expand/collapse (from clicking a node's `toggle` button) overrides
+  `collapsedDepth` and declarative search-driven auto-expansion for that path. Imperative
+  `searchNext()`/`searchPrevious()` navigation may reopen the ancestors of the selected result so
+  the active match is never hidden; otherwise the override persists until `data` is reassigned with
+  a different shape.
 - Per-node copy buttons call `stopPropagation()` on click so clicking one doesn't also toggle the
   row's expand/collapse state.
 
@@ -7517,10 +8215,11 @@ via an internal `<lr-live-region>` in polite mode.
 
 A caret-anchored, keyboard-navigable popover for `@`-mention and `/`-slash-command autocomplete
 inside a plain-text `<textarea>`/`<input>` the host owns. First-party invention (no Web Awesome
-equivalent). It never takes DOM focus itself — the host's own input keeps focus, and this
-component conveys the active row via `activeDescendantId` for the host to apply as its own
-input's `aria-activedescendant`, the same pattern `<lr-select>`/`<lr-combobox>` use for their
-own listbox.
+equivalent). On platforms accepting cross-root ARIA element reflection, the host's own input keeps
+focus and `syncActiveDescendant()` points it at the active option. Where that reference is rejected,
+`focusActiveOption()` moves real focus into this component's shadow listbox so the focus owner and
+option share one tree scope. A string `aria-activedescendant` cannot resolve from a host input in
+the document into an option in this component's shadow root.
 
 **Properties:**
 - `anchor?: HTMLElement` (attribute: false) — the element to position the popup relative to. A
@@ -7540,18 +8239,26 @@ own listbox.
 - `filteredItems: MentionItem[]` — read-only getter; `items` filtered by `query` via `filter` (or
   the built-in default). Empty `query` returns `items` unfiltered.
 - `activeDescendantId: string | null` — read-only getter; the `id` of the currently-highlighted
-  row, or `null` while closed or when `filteredItems` is empty.
-- `listboxId: string` — read-only getter; the `id` of the `role="listbox"` element, for a host that
-  also wants to wire `aria-controls`.
-
-**Methods:** `handleKeyDown(e: KeyboardEvent): boolean` — the host's own text-control `keydown`
-handler calls this while the popover is open. Handles `ArrowDown`/`ArrowUp` (moves the highlight) and
-`Enter`/`Tab` (commits the highlighted row) — both pairs return `false` with no `preventDefault()`
-when `filteredItems` is empty, letting the keystroke fall through to the host's own control unchanged
-(e.g. the textarea's caret still moves to the next line on ArrowDown when there's nothing to
-navigate); `Escape` always closes with no selection and returns `true`. Returns `true` whenever the
-key was intercepted (`preventDefault()` already called) and the host should not also act on it,
-`false` otherwise (including for any key this method doesn't recognize).
+  internal row, or `null` while closed or when `filteredItems` is empty. Useful for diagnostics and
+  same-tree consumers; do not copy it to an external control as a string IDREF.
+- `activeDescendantElement: HTMLElement | null` — read-only getter; the highlighted shadow option
+  for the platform's element-reference ARIA API.
+- `listboxId: string` — read-only getter; the internal `id` of the `role="listbox"` element. Like
+  `activeDescendantId`, it cannot form a cross-shadow string IDREF from a host input.
+
+**Methods:**
+- `handleKeyDown(e: KeyboardEvent): boolean` — the host's own text-control `keydown` handler calls
+  this while the popover is open. Handles `ArrowDown`/`ArrowUp` (moves the highlight) and
+  `Enter`/`Tab` (commits the highlighted row) — both pairs return `false` with no
+  `preventDefault()` when `filteredItems` is empty, letting the keystroke fall through to the
+  host's own control unchanged. `Escape` closes with no selection. Returns `true` whenever the key
+  was intercepted and `false` for keys the method does not recognize.
+- `syncActiveDescendant(control: HTMLElement): boolean` — clears any string
+  `aria-activedescendant`, then applies `ariaActiveDescendantElement` when the platform accepts the
+  cross-root reference. Returns whether that reference was accepted.
+- `focusActiveOption(): Promise<boolean>` — same-tree fallback after a consumed navigation key
+  when `syncActiveDescendant()` returns `false`. Focuses the active option, lets the popover handle
+  subsequent navigation, and restores focus to `anchor` when the popover closes.
 
 **Exported types:** `MentionItem { id: string; label: string; description?: string; icon?: string
 }`; `MentionFilter = (item: MentionItem, query: string) => boolean`; `MentionSelectDetail { id:
@@ -7593,7 +8300,13 @@ available space. See `lr-tour` for the shared-clamp note.
   const popover = document.getElementById('mentions');
 
   textarea.addEventListener('keydown', (e) => {
-    if (popover.open && popover.handleKeyDown(e)) return; // consumed
+    if (popover.open && popover.handleKeyDown(e)) {
+      if (!popover.syncActiveDescendant(textarea) &&
+          (e.key === 'ArrowDown' || e.key === 'ArrowUp')) {
+        void popover.focusActiveOption();
+      }
+      return;
+    }
   });
   textarea.addEventListener('input', () => {
     popover.anchor = textarea;
@@ -7603,6 +8316,7 @@ available space. See `lr-tour` for the shared-clamp note.
     ];
     popover.query = 'a'; // detected since the trigger character
     popover.open = true;
+    popover.updateComplete.then(() => popover.syncActiveDescendant(textarea));
   });
 
   popover.addEventListener('lr-mention-select', (e) => {
@@ -7613,11 +8327,11 @@ available space. See `lr-tour` for the shared-clamp note.
 
 Integration is entirely the host's responsibility: detect a mention/command trigger in the host's
 own `input` handling, set `anchor`/`items`/`query` and flip `open = true`, forward every `keydown`
-through `handleKeyDown()` while open, and keep the host's own input's `aria-activedescendant` (and
-optionally `aria-controls`, via `listboxId`) in sync with `activeDescendantId`. Setting `open =
-false` whenever the query stops looking like an active mention context (a space typed, the trigger
-deleted, the input blurred, …) is also the host's job — `lr-mention-close` fires automatically
-from that, there is no separate "tell it to close" call needed.
+through `handleKeyDown()` while open, and call `syncActiveDescendant()` after opening and after each
+consumed navigation key. If it returns `false`, call `focusActiveOption()` after the first consumed
+ArrowUp/ArrowDown so the fallback owns navigation from then on. Setting `open = false` whenever the
+query stops looking like an active mention context (a space typed, the trigger deleted, the input
+blurred, …) is also the host's job — `lr-mention-close` fires automatically from that.
 
 Positioning measures exactly where the caret currently paints via a hidden-mirror-element technique
 (`caretClientRect()`) and positions against that single point with `internal/positioner.js`'s
@@ -7629,6 +8343,9 @@ fresh `query` is the proxy for "the caret may have moved").
 - a host-level `aria-label` attribute on `<lr-mention-popover>` now takes priority over `label`
   (and its localized default) when resolving `[part="listbox"]`'s accessible name — previously it
   was silently ignored. Matches the same fallback on `<lr-combobox>`/`<lr-table>`.
+- Never copy `activeDescendantId` or `listboxId` onto a document-owned control as a string ARIA
+  IDREF; shadow-root IDs are outside that control's tree scope. Use `syncActiveDescendant()` and its
+  `focusActiveOption()` fallback.
 - The popover opens pre-highlighted on the top match (index 0), unlike `<lr-combobox>`'s own
   listbox which opens with nothing highlighted (`-1`) — a bare Enter right after opening commits
   immediately.
@@ -7675,6 +8392,9 @@ First-party invention (no Web Awesome equivalent).
 - `contextLines: number | undefined` (attribute: `context-lines`) — keeps this many unchanged
   lines around each change and collapses longer unchanged runs into a localized fold marker. The
   default `undefined` shows every line; negative and non-finite values also disable folding.
+- `maxLines: number = 5000` (attribute `max-lines`) — maximum logical lines accepted on either
+  side. Larger input renders the localized `diffViewTooLarge` fallback without computing or
+  highlighting the diff. Set the property to `Infinity` explicitly to opt into unbounded diffing.
 
 **Events:** `lr-copy` (`detail: { text: string }` — the full unified-diff text, fired on
 copy-button activation regardless of whether the clipboard write actually succeeded).
@@ -7685,7 +8405,8 @@ copy-button activation regardless of whether the clipboard write actually succee
 `data-type="equal"|"add"|"remove"|"empty"|"fold"` — `"empty"` is an unbalanced-replace placeholder cell in
 `layout="split"` and never carries a `+`/`-` prefix; `"fold"` is the localized unchanged-lines
 marker), `copy-button` (the copy affordance, only
-rendered while `copyable`), `side` (one column in `layout="split"`, `data-side="old"|"new"`).
+rendered while `copyable`), `limit` (the localized over-`maxLines` fallback), `side` (one column in
+`layout="split"`, `data-side="old"|"new"`).
 
 **Themeable custom properties:** `--lr-diff-view-font` (default `var(--lr-font-mono)`), plus
 shared tokens `--lr-color-border`/`-surface`/`-success`/`-success-quiet`/`-danger`/
@@ -7713,13 +8434,22 @@ same line-diff function this component's own `render()`/copy handler call, expos
 consumer can compute or unit-test the same alignment without instantiating the element at all.
 
 **Known gotchas:**
-- the alignment is a genuine O(n·m) longest-common-subsequence dynamic program over lines (split on
-  `\n`), not a naive "every removed line then every added line" — fine for a typical
-  tool-call/transcript-sized diff, but a very large pair of texts costs quadratic time/memory;
-  there's no line-count guard or chunking of its own.
-- `oldText`/`newText` are recomputed into the diff on every render — this component keeps no separate
-  cached diff state, so binding either property to something that changes on every keystroke
-  recomputes the whole alignment each time.
+- line splitting normalizes LF, CRLF, and lone CR endings before alignment and syntax-token indexing,
+  so files that differ only by line-ending convention do not appear wholly changed.
+- alignment uses Hirschberg longest-common-subsequence matching: O(n·m) time with linear working
+  memory. The 5,000-line per-side default ceiling bounds pathological inputs; `Infinity` is an
+  explicit performance-risk opt-out.
+- the computed `diffOps` state is cached and recomputed only when `oldText`, `newText`, or
+  `maxLines` changes. Copy-confirmation and other unrelated renders reuse the cached alignment.
+
+**Additional API surface:**
+
+- `--lr-diff-view-add-background` — Added-line background.
+- `--lr-diff-view-add-color` — Added-line text color.
+- `--lr-diff-view-remove-background` — Removed-line background.
+- `--lr-diff-view-remove-color` — Removed-line text color.
+- `--lr-diff-view-fold-color` — Fold-marker text color.
+- `--lr-diff-view-fold-background` — Fold-marker background.
 
 ---
 
@@ -7949,6 +8679,10 @@ The two height knobs work as a pair on `[part='field-input']`, the same way
 - The host carries a `:state(blank)` custom state whenever `value === ''`, and `data-invalid` only
   once touched (first blur out of the whole control) and actually invalid.
 
+**Additional API surface:**
+
+- `click()` — Activates the first native field in locale order.
+
 ## `lr-random-content`
 
 Shows a chosen subset of its slotted children and hides the rest — A/B copy testing, testimonial
@@ -7965,6 +8699,8 @@ children; nothing is moved or cloned.
 - `animation: 'none' | 'fade' | 'fade-up' | 'fade-down' | 'fade-left' | 'fade-right' = 'none'`
   (reflected) — entrance effect applied to a child the instant it becomes shown
 - `autoplay: boolean = false` (reflected)
+- `paused: boolean = false` (reflected) — suppresses autoplay. The built-in pause/resume action
+  toggles this state; a programmatic assignment remains silent.
 - `autoplayInterval: number = 3000` (attribute `autoplay-interval`) — clamped to a 1000 ms floor
 
 **Methods:** `randomize(): HTMLElement[]` — re-selects using the current `mode`, applies
@@ -7980,7 +8716,8 @@ each autoplay tick; never when the eligible pool is empty.
 **CSS parts:** `base` — the wrapper around the default slot; carries `role="status"`,
 `aria-atomic="true"`, and `aria-live="polite"`, downgraded to `aria-live="off"` while `autoplay` is
 on (a self-rotating region announcing on every tick would be spam). A host `aria-label` attribute is
-forwarded onto it.
+forwarded onto it. `pause-button` — the localized autoplay pause/resume action, rendered only while
+`autoplay` is enabled and exposed as a toggle with `aria-pressed`.
 
 **Themeable custom properties:** `--lr-random-content-animation-duration` (default `300ms`),
 `--lr-random-content-animation-easing` (default `ease`),
@@ -7988,8 +8725,8 @@ forwarded onto it.
 directional `fade-*` effects).
 
 **Known gotchas:**
-- There is no built-in trigger UI (no next/previous/shuffle button) and therefore no keyboard
-  interaction: selection changes only via `autoplay` or `randomize()`.
+- There is no next/previous/shuffle action; the only built-in control is the autoplay pause/resume
+  button. Selection changes via autoplay or `randomize()`.
 - Autoplay is suppressed entirely under `prefers-reduced-motion: reduce`, and whenever the eligible
   pool has fewer than 2 children. The preference is re-observed live, not just read once.
 - `fade-left`/`fade-right` are physical-direction transforms (upstream naming), deliberately **not**
@@ -8252,6 +8989,10 @@ import '@aceshooting/lyra-ui/components/media/flag/flag-peer.js';
   (`variant="detailed"` is the replacement); left unset, `variant` falls back to honoring `detailed`
   for one more minor version before removal.
 
+**Additional API surface:**
+
+- `part="error"` — Localized alert rendered when the optional peer resolver is unavailable or fails.
+
 ---
 
 ## `lr-playback`
@@ -8268,8 +9009,8 @@ Steps an index through `[0, length)` on a fixed interval — play/pause for time
   change-tracking sees it and auto-pauses on `hidden = true`)
 
 **Methods:** `play()`, `pause()`, `toggle()`, `next()`, `previous()`, `goTo(index: number)` — all
-idempotent/clamped; `length <= 1` is a no-op degenerate case. `focus(options?)` and `blur()` forward
-to the play button.
+idempotent/clamped; `length <= 1` is a no-op degenerate case. `focus(options?)`, `blur()`, and
+`click()` forward to the play button.
 
 **Events:** `lr-play`, `lr-pause` (no detail), `lr-step` (`detail: { index }`, fired on every
 tick and manual step); internal `focus`/`blur` are bridged as bubbling, composed host events.
@@ -8380,13 +9121,19 @@ not installed)
 **Themeable custom properties:** shared tokens only — `--lr-space-xs/-s`, `--lr-color-surface`,
 `--lr-color-border`, `--lr-shadow`, `--lr-radius`.
 
-**Optional peer deps:** `maplibre-gl` (lazy-loaded; consumer must **separately** `import
-'maplibre-gl/dist/maplibre-gl.css'` once — the component does not do this for you).
+**Optional peer deps:** `maplibre-gl` (lazy-loaded). MapLibre v6 is ESM-only and requires WebGL2.
+The consumer must **separately** import `maplibre-gl/dist/maplibre-gl.css` and configure the v6
+module-worker URL for its bundler once — the component cannot choose a bundler-specific worker URL.
+For Vite:
 
 ```html
 <lr-map center="[2.35, 48.85]" zoom="10"></lr-map>
-<script>
+<script type="module">
+  import { setWorkerUrl } from 'maplibre-gl';
+  import workerUrl from 'maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url';
   import 'maplibre-gl/dist/maplibre-gl.css';
+  setWorkerUrl(workerUrl);
+
   const m = document.querySelector('lr-map');
   m.choropleth = {
     sourceId: 'regions',
@@ -8400,6 +9147,10 @@ not installed)
 </script>
 ```
 
+Webpack, esbuild, Rollup, and direct-browser ESM use different worker URL forms; use MapLibre's ESM
+installation guide for the matching setup:
+https://maplibre.org/maplibre-gl-js/docs/#esm.
+
 **Known gotchas:**
 - clearing or swapping the choropleth no longer leaks the old layer: setting `choropleth =
   undefined`, or changing `choropleth.sourceId` to a different value, now calls `removeLayer`/
@@ -8475,12 +9226,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
@@ -8504,17 +9267,18 @@ tokens — `--lr-space-xs`, `--lr-space-l`,
 **Optional peer deps:** none.
 
 ```html
-<lr-file-input multiple accept=".csv,.xlsx" allowed-mime-types='["text/csv"]'></lr-file-input>
+<lr-file-input id="dataset-files" multiple accept=".csv,.xlsx"></lr-file-input>
 <script>
-  document.querySelector('lr-file-input').addEventListener('lr-files', (e) => {
+  const input = document.querySelector('#dataset-files');
+  input.allowedMimeTypes = ['text/csv'];
+  input.addEventListener('lr-files', (e) => {
     console.log('accepted:', e.detail.files, 'rejected:', e.detail.rejected); // rejected[i].reason
   });
 </script>
 ```
 
 Note: `allowedMimeTypes`/`forbiddenMimeTypes` are complex properties (`attribute: false`) — set
-them via JS (`el.allowedMimeTypes = [...]`), not as a JSON string attribute; the snippet above is
-illustrative of intent only.
+them via JS (`el.allowedMimeTypes = [...]`), not as a JSON string attribute.
 
 `accept.ts` exports `matchesAccept(file, accept, assumeExtensionMatch?)` (internal — not
 re-exported from the package root) — parses the same three `accept` forms the browser's native
@@ -8527,8 +9291,7 @@ an extension-only `accept` list.
 **Known gotchas:**
 - Paste-from-clipboard **is** supported and on by default: a `paste` event on the dropzone reads
   `e.clipboardData.files` and routes it through the same accept/reject classification as a drop.
-  Set `paste="false"` (or `.paste = false`) to opt out. (The package README's "Known limitations"
-  entry claiming there is no paste support, and none for dragged folders, is stale — both work.)
+  Set `paste="false"` (or `.paste = false`) to opt out.
 - Dragged folders **are** detected via `webkitGetAsEntry()` and reported as
   `rejected[].reason === 'directory'` (paired with a synthetic zero-byte `File` carrying the folder
   name), not silently accepted as a phantom file.
@@ -8559,6 +9322,8 @@ Before/after comparison surface with two named slots and a keyboard-accessible n
 **Events:** `lr-position-change` (`detail: { position }`), plus composed `focus` and `blur` events
 from the internal range handle.
 
+**Methods:** `focus(options?)`, `blur()`, and `click()` forward to the internal range handle.
+
 **Slots:** `before`, `after`.
 
 **CSS parts:** `base`, `before`, `after`, `divider`, and `handle`.
@@ -8802,6 +9567,9 @@ drop-in still does something useful, but `lr-open` fires first — a host callin
 `preventDefault()` on it suppresses that default download/open so it can substitute its own
 handling.
 
+**Methods:** `focus(options?)`, `blur()`, and `click()` forward to the primary action for the
+current media kind.
+
 **Slots:** none.
 
 **CSS parts:** `base` (a `<button>` for `kind="image"`, a plain wrapper `<div>` for `kind="video"`,
@@ -8938,6 +9706,10 @@ hidden via CSS by default, exposed as a part only so a consumer can override tha
   scope-limited by design to firing `lr-camera-request`/`lr-audio-request` and nothing else. The
   hidden input is only rendered when `capabilities` contains `files` or `image`.
 
+**Additional API surface:**
+
+- `click()` — Activates the internal attachment trigger.
+
 ---
 
 ## `lr-avatar`
@@ -9057,6 +9829,10 @@ backgrounded circle around the button; only rendered once loaded and error-free)
   browser's native decode loop keeps running while visually covered; only opacity and `aria-hidden`
   swap.
 
+**Additional API surface:**
+
+- `click()` — Activate the play/pause control.
+
 ## `lr-animation`
 
 Declaratively animates one slotted element through the native Web Animations API.
@@ -9295,12 +10071,18 @@ mode is on. The toggle carries its own glyph in `--lr-color-text`, so keep a 4.5
 when overriding the background. `--lr-image-viewer-highlight-active-color` (default
 `var(--lr-color-brand)`) — the outline of the `[part='highlight']` matching `activeHighlightId`,
 independent of the per-tone border colors, so the active box stays distinguishable whatever tone it
-carries. All three are declared as inline `var()` fallbacks at the point of use rather than on
-`:host`, so each can be set on the element *or on any ancestor*: `::part(highlight)[data-active]` is
-invalid CSS — Shadow Parts forbids an attribute selector after `::part()` — which previously left
-overriding the library-wide `--lr-color-brand`/`--lr-color-brand-quiet` tokens as the only lever,
-repainting every other element that read them. Unset, each falls back to the token its rule used
-before.
+carries. Highlight tone styling is exposed through `--lr-image-viewer-highlight-border`,
+`--lr-image-viewer-highlight-bg`, and the tone-specific
+`--lr-image-viewer-highlight-success-border`, `--lr-image-viewer-highlight-success-bg`,
+`--lr-image-viewer-highlight-warning-border`, `--lr-image-viewer-highlight-warning-bg`,
+`--lr-image-viewer-highlight-danger-border`, `--lr-image-viewer-highlight-danger-bg`,
+`--lr-image-viewer-highlight-neutral-border`, and `--lr-image-viewer-highlight-neutral-bg`
+properties. These properties are declared as inline `var()` fallbacks at the point of use rather
+than on `:host`, so each can be set on the element *or on any ancestor*:
+`::part(highlight)[data-active]` is invalid CSS — Shadow Parts forbids an attribute selector after
+`::part()` — which previously left overriding the library-wide
+`--lr-color-brand`/`--lr-color-brand-quiet` tokens as the only lever, repainting every other
+element that read them. Unset, each falls back to the token its rule used before.
 
 ## `lr-av-player`
 
@@ -9312,8 +10094,8 @@ distinct from `<lr-transcript-feed>` (live captions for an in-progress voice ses
 `anchorKinds: ['time-range']` only — no text selection is bound. The transcript virtualizes through
 `<lr-virtual-list>` the same way `lr-pdf-viewer` virtualizes pages.
 
-**Properties:** `src: string = ''`, `name: string = ''`, `kind?: 'audio' | 'video'` (attribute:
-false auto-detection override), `mimeType: string = ''` (attribute `mime-type`), `poster: string =
+**Properties:** `src: string = ''`, `name: string = ''`, `kind?: 'audio' | 'video'`
+(attribute-backed auto-detection override), `mimeType: string = ''` (attribute `mime-type`), `poster: string =
 ''`, `loop: boolean = false`, `muted: boolean = false`, `preload: 'none' | 'metadata' | 'auto' =
 'metadata'`, `playbackRate: number = 1` (attribute `playback-rate`, reflected), `rates: number[] =
 [0.75, 1, 1.25, 1.5, 2]` (attribute: false), `cues: LyraAvCue[] = []` (attribute: false), `peaks:
@@ -9393,15 +10175,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 +10209,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 +10231,39 @@ Chart.js wrapper every other `lr-*-chart` tag subclasses; supports both a simpli
 - `chartArea: LyraChartArea | undefined` (readonly) — current Chart.js chart-area geometry in
   canvas-local coordinates (`top`, `left`, `right`, `bottom`, `width`, `height`), when a chart is
   drawn
+- `appendData(label, values, maxPoints?)` — appends one aligned numeric category and optionally
+  keeps only the newest `maxPoints`; point-based scatter/bubble series are left unchanged
+
+**Methods:** `resetZoom()` resets any active zoom/pan to the original view. `refreshTheme()` forces
+a redraw so the `--lr-chart-*` tokens below are re-read from the current computed style. A
+built-in `ThemeWatcher` now calls this automatically when `prefers-color-scheme` flips or an
+ancestor's `class`/`style`/`data-theme`/`data-color-scheme` attribute mutates — the most common
+theme-toggle mechanisms — so a consumer rarely needs to call it by hand; it remains public as the
+escape hatch for theme changes those signals can't observe. `exportData('csv' | 'png')` returns a
+spreadsheet-safe CSV snapshot or the current PNG data URL when Chart.js is loaded.
+
+The instance method `seriesPalette(): string[]` resolves the categorical series ramp
+(`--lr-color-chart-1..8`) through `getComputedStyle` and returns the concrete, theme-aware colors —
+the exact same values the chart hands any series that sets no `color` of its own. Each internal
+token resolves through the matching application input (`--lr-theme-color-chart-1..8`), so theme
+overrides are included.
+
+The module also exports `seriesPalette(scope?: Element | null): string[]`, which can run before a
+chart exists. Omit `scope` to read `document.documentElement`, pass an element to resolve its theme
+scope, or pass `null` to request the light-mode fallback directly. When a scope has no component
+token layer yet, the helper reads the `--lr-theme-color-chart-N` inputs directly. Both forms return
+a fresh eight-color array each call (safe to mutate) and let chart-adjacent UI, KPI tiles, or the
+`Series` array itself come from one source of truth.
 
-**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)
+```ts
+import { seriesPalette } from '@aceshooting/lyra-ui/components/charts/chart/chart.js';
+
+const colors = seriesPalette();
+const series = [
+  { label: 'Revenue', data: [12, 19], color: colors[0] },
+  { label: 'Costs', data: [7, 11], color: colors[1] },
+];
+```
 
 **Events:** `lr-zoom` (`detail: { zoomed: boolean }`, fired on zoom-complete and on
 `resetZoom()`), `lr-point-click` (fired when a click lands on, or nearest to — intersect-only —
@@ -9477,10 +10309,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 +10416,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 +10448,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 +10512,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 +10534,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 +10578,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 +10644,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`,
@@ -9802,8 +10653,8 @@ browser). Does **not** extend `LyraChart` — a deliberately bespoke API.
 (also `getComputedStyle`-resolved on every draw), but declared in its own stylesheet, not a
 re-export: `lr-box-plot` has no `zoom`, so no `reset-zoom-button` chrome exists here.
 
-**Optional peer deps:** `@sgratzl/chartjs-chart-boxplot` (plus `chart.js` transitively, loaded
-independently of the base `chart-loader.ts`).
+**Optional peer deps:** `@sgratzl/chartjs-chart-boxplot` plus `chart.js`; Chart.js is obtained
+through the same cached `chart-loader.ts` used by `lr-chart`.
 
 ```html
 <lr-box-plot y-label="Latency (ms)"></lr-box-plot>
@@ -9821,10 +10672,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`
@@ -9918,7 +10778,10 @@ used both for `status="converting"` and this component's own in-flight text fetc
 rendered when `src` is set *and* passes the link-safe scheme allowlist — see the URL-safety note
 above; excludes `data:` even though the other two sinks allow it), `highlight-layer` (wrapper around
 every rendered region highlight, image format only), `region-highlight` (one region highlight,
-`data-tone`, `data-active`; image format only), `frame-viewport`/`frame-content`/`frame-controls`/
+`data-tone`, `data-active`; image format only), `region-highlight-target` (transparent activation
+geometry with a minimum hit area independent of the visual rectangle), `highlight-actions`
+(non-overlapping actions used when multiple minimum hit areas would overlap),
+`region-highlight-action` (one action in that list), `frame-viewport`/`frame-content`/`frame-controls`/
 `frame-zoom-in`/`frame-zoom-out`/`frame-reset` (forwarded from the internal `<lr-zoomable-frame>`
 while `zoomable`; image format only)
 
@@ -9926,7 +10789,8 @@ while `zoomable`; image format only)
 consumer-tunable scroll cap on `[part="body"]`, set from `max-height`; `none` means the preview grows
 with its content until a caller opts in. `--lr-document-preview-font` (default `ui-monospace,
 SFMono-Regular, Menlo, Consolas, monospace`) and `--lr-document-preview-spin-duration` (default
-`0.8s`, stopped under reduced motion). `--lr-document-preview-progress` (default `0`) — a unitless
+`var(--lr-transition-ambient)`, stopped under reduced motion). `--lr-document-preview-progress`
+(default `0`) — a unitless
 0–100 number the determinate spinner's `conic-gradient` fill reads; written inline on the ring by
 the component itself from the clamped `progress` property, so overriding it only makes sense to
 repaint the fraction. `--lr-document-preview-active-border` (default
@@ -9937,7 +10801,11 @@ state hooks it is an inline `var()` fallback at the point of use rather than a `
 so it can be set on the element or on any ancestor — `::part(region-highlight)[data-active]` is
 invalid CSS (Shadow Parts forbids an attribute selector after `::part()`), which previously left
 re-pointing the shared `--lr-color-warning`/`--lr-color-brand` tokens as the only lever, repainting
-every other element that read them. Plus shared tokens
+every other element that read them. The tone-specific resting border and hover tint use
+`--lr-document-preview-highlight-accent-color`, `--lr-document-preview-highlight-success-color`,
+`--lr-document-preview-highlight-warning-color`, `--lr-document-preview-highlight-danger-color`,
+and `--lr-document-preview-highlight-neutral-color` (defaulting respectively to the matching
+brand/success/warning/danger/neutral color tokens). Plus shared tokens
 `--lr-color-border`, `--lr-radius`, `--lr-color-surface`, `--lr-space-s/-m/-l/-xs`,
 `--lr-color-text`, `--lr-color-text-quiet`, `--lr-color-danger`, `--lr-color-brand`,
 `--lr-color-on-brand`, `--lr-focus-ring-width/-color/-offset`, `--lr-transition-fast`.
@@ -9992,9 +10860,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
@@ -10030,10 +10899,11 @@ type. First-party invention.
 - `lr-download` — `detail: { src, filename }`, emitted when the native safe download action is
   activated. The browser download itself is handled by the link.
 - `lr-anchor-result` — `detail: { found }`. Emitted by this shell as `{ found: false }` once per
-  applied `anchor` when the resolved renderer can't honor it (it declares no `capabilities.anchors`,
-  or none matching the anchor's `kind`), when the lazy renderer failed to load, or when the file fell
-  back to `<lr-document-preview>`. A capable renderer instead emits its own `lr-anchor-result` from
-  its embedded `DocumentAnchorTarget` mixin, which composes up through this element unchanged — the
+  applied `anchor` when a resolved renderer can't honor it (it declares no `capabilities.anchors`,
+  or none matching the anchor's `kind`). When the file uses `<lr-document-preview>`—including after
+  a lazy renderer fails to load—the shell delegates to that preview's `scrollToAnchor()` and emits
+  its actual `found` result. A capable renderer instead emits its own `lr-anchor-result` from its
+  embedded `DocumentAnchorTarget` mixin, which composes up through this element unchanged — the
   shell stays silent in that case, so the event fires exactly once either way. A string `anchor`
   (a highlight id) counts as supported by any renderer declaring at least one anchor kind.
 
@@ -10114,6 +10984,17 @@ currently active search match, also carries `search-match`).
 
 **Themeable custom properties:** `--lr-docx-viewer-max-height` (default `none`) — maximum block size
 of `[part="body"]`; also settable via the `max-height` property, which writes this token inline.
+Highlight backgrounds are independently themeable with
+`--lr-docx-viewer-highlight-accent-background`,
+`--lr-docx-viewer-highlight-success-background`,
+`--lr-docx-viewer-highlight-warning-background`,
+`--lr-docx-viewer-highlight-danger-background`, and
+`--lr-docx-viewer-highlight-neutral-background`, defaulting to the matching quiet color tokens.
+`--lr-docx-viewer-highlight-active-background` and
+`--lr-docx-viewer-highlight-active-outline` style the active host highlight.
+`--lr-docx-viewer-search-match-background`,
+`--lr-docx-viewer-search-match-active-background`, and
+`--lr-docx-viewer-search-match-active-foreground` style resting and active search matches.
 
 **Optional peer dependencies:** install `mammoth` and `dompurify` with `pnpm add mammoth dompurify`.
 The component registers an eager `application/vnd.openxmlformats-officedocument.wordprocessingml.document`
@@ -10144,7 +11025,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
@@ -10163,8 +11049,8 @@ of `[part="body"]`; also settable via the `max-height` property, which writes th
 
 **Optional peer dependencies:** install `postal-mime` and `dompurify` with
 `pnpm add postal-mime dompurify`. The component registers `message/rfc822` and falls back to
-matching `.eml` filenames in `<lr-document-viewer>`. Deviates from the shared degraded-render
-contract: an absent `postal-mime` renders `[part="error"]` with the localized
+matching `.eml` filenames in `<lr-document-viewer>`. Fail-closed behavior is explicit: an absent
+`postal-mime` renders `[part="error"]` with the localized
 `emailViewerMissingParser` message (nothing is parseable without it), and an HTML-only message
 (no `text/plain` alternative) with `dompurify` absent renders the localized
 `documentViewerMissingSanitizer` message rather than silently showing an empty body.
@@ -10174,7 +11060,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 +11089,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
@@ -10254,6 +11150,10 @@ clears the query, matches, and painted search annotation.
 `mount`, `error`, and `announcer` (the visually-hidden `role="status"` region search results
 announce through).
 
+The toolbar buttons use the component-specific localized labels `ebookViewerPreviousChapter` and
+`ebookViewerNextChapter` (English: “Previous chapter” / “Next chapter”), so they remain
+unambiguous beside other previous/next controls and are overridable through `.strings`.
+
 **Optional peer dependency:** install `epubjs` with `pnpm add epubjs`. The document-viewer registry
 matches `application/epub+zip` and `.epub` filenames, declaring `{ anchors: ['cfi', 'text-quote'],
 search: true, textSelect: true }` capabilities.
@@ -10276,10 +11176,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`.
@@ -10319,6 +11223,9 @@ Enter/Space.
 
 **CSS parts:** `base`, `body`, `svg`, `spinner`, `error`, `highlight-layer` (wrapper around every
 rendered region highlight), `region-highlight` (one region highlight, `data-tone`, `data-active`),
+`region-highlight-target` (transparent activation geometry with an independent minimum hit area),
+`highlight-actions` (non-overlapping actions for multiple highlights), `region-highlight-action`
+(one action in that list),
 `frame-viewport`/`frame-content`/`frame-controls`/`frame-zoom-in`/`frame-zoom-out`/`frame-reset`
 (forwarded from the internal `<lr-zoomable-frame>` while `zoomable`).
 
@@ -10331,7 +11238,11 @@ inline `var()` fallback at the point of use rather than a `:host` declaration, s
 the element *or on any ancestor*: `::part(region-highlight)[data-active]` is invalid CSS — Shadow
 Parts forbids an attribute selector after `::part()` — so re-pointing a shared `--lr-color-*` token,
 and repainting everything else reading it, was previously the only way. Unset, it falls back to
-exactly the tokens the rule used before.
+exactly the tokens the rule used before. The tone-specific resting border and hover tint use
+`--lr-svg-viewer-highlight-accent-color`, `--lr-svg-viewer-highlight-success-color`,
+`--lr-svg-viewer-highlight-warning-color`, `--lr-svg-viewer-highlight-danger-color`, and
+`--lr-svg-viewer-highlight-neutral-color` (defaulting respectively to the matching
+brand/success/warning/danger/neutral color tokens).
 
 **Optional peer dependency:** `dompurify`.
 
@@ -10343,7 +11254,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 +11335,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.
 
@@ -10508,7 +11429,7 @@ through the exported parts above rather than through dedicated custom properties
 
 **Optional peer dependency:** install `pdfjs-dist` with `pnpm add pdfjs-dist`. The component registers
 a lazy `application/pdf` renderer with `<lr-document-viewer>` so the PDF library is loaded only when
-a PDF is opened. Deviates from the shared degraded-render contract: an absent `pdfjs-dist` renders
+a PDF is opened. An absent `pdfjs-dist` fails closed and renders
 `[part="error"]` with the localized `pdfViewerMissingLibrary` message — there is no partial PDF
 rendering without it.
 
@@ -10541,9 +11462,11 @@ Enter/Space. `lr-anchor-result` (`detail: { found }`) — fired after an `anchor
 `scrollToAnchor()` call. `lr-search-change` (`detail: { query, matchCount, activeIndex }`) — from
 `search()`/`searchNext()`/`searchPrevious()`/`clearSearch()`.
 
-**CSS parts:** `base`, `tabs`, `sheet`, `header-row`, `data-row`, `cell`, `cell-highlight` (a cell
-covered by a `highlights` entry), `rows`, `spinner`, and `error`. `data-row`, `cell` and
-`cell-highlight` are rendered inside the internal `<lr-virtual-list>` and forwarded via
+**CSS parts:** `base`, `tabs`, `sheet`, `header-row`, `data-row`, `cell`, `cell-highlight` (a
+structural cell covered by a `highlights` entry), `cell-highlight-action` (the native button
+filling a highlighted cell; focusable and emits `lr-highlight-activate`), `rows`, `spinner`, and
+`error`. `data-row`, `cell`, `cell-highlight`, and `cell-highlight-action` are rendered inside the
+internal `<lr-virtual-list>` and forwarded via
 `exportparts`, so `lr-spreadsheet-viewer::part(cell)` reaches them from a consumer stylesheet.
 
 **Themeable custom properties:** `--lr-spreadsheet-viewer-highlight-color` (default
@@ -10588,9 +11511,11 @@ Enter/Space. `lr-anchor-result` (`detail: { found }`) — fired after an `anchor
 `scrollToAnchor()` call. `lr-search-change` (`detail: { query, matchCount, activeIndex }`) — from
 `search()`/`searchNext()`/`searchPrevious()`/`clearSearch()`.
 
-**CSS parts:** `base`, `sheet`, `header-row`, `data-row`, `cell`, `cell-highlight` (a cell covered by
-a `highlights` entry), `rows`, `spinner`, and `error`. `data-row`, `cell` and `cell-highlight` are
-rendered inside the internal `<lr-virtual-list>` and forwarded via `exportparts`, so
+**CSS parts:** `base`, `sheet`, `header-row`, `data-row`, `cell`, `cell-highlight` (a structural
+cell covered by a `highlights` entry), `cell-highlight-action` (the native button filling a
+highlighted cell; emits `lr-highlight-activate`), `rows`, `spinner`, and `error`. `data-row`,
+`cell`, `cell-highlight`, and `cell-highlight-action` are rendered inside the internal
+`<lr-virtual-list>` and forwarded via `exportparts`, so
 `lr-csv-viewer::part(cell)` reaches them from a consumer stylesheet.
 
 **Themeable custom properties:** `--lr-csv-viewer-max-height` (default `none`) — maximum block size
@@ -10635,13 +11560,19 @@ 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`:
   `'blocked-url'` (`src` failed the allowlist; `fetch()` never ran), `'network'` (`fetch()` rejected),
   `'http'` (response not `ok`; `status` carries the code), `'missing-sanitizer'` (the optional
   `dompurify` peer failed to load), or `'resource-too-large'` (the body exceeded the shared 25 MB
-  cap). `status` is `0` for every reason but `'http'`.
+  cap). Non-HTTP reasons use status `0`; `'http'` normally carries the response code, but an opaque
+  `mode="no-cors"` response is also classified as `'http'` with status `0`.
 
 **Slots:** default — fallback content shown until (or unless) a fetch succeeds. It is overwritten by
 the sanitized fragment on success, and left untouched on failure (as is any previously successful
@@ -10649,9 +11580,9 @@ include).
 
 **CSS parts:** `base` — the `display: contents` wrapper around the default slot.
 
-Deviates from the shared degraded-render contract: an absent `dompurify` fires
-`lr-include-error` with `reason: 'missing-sanitizer'` and leaves the existing content in place —
-unsanitized markup is never transcluded.
+An absent `dompurify` fails closed: it fires `lr-include-error` with
+`reason: 'missing-sanitizer'` and leaves the existing content in place — unsanitized markup is
+never transcluded.
 
 ## `lr-highlight-layer`
 
@@ -10670,8 +11601,22 @@ re-click of the same source citation).
 **Events:** `lr-highlight-activate` — a rect was activated (click, or Enter/Space while focused).
 `detail: { id }`.
 
-**CSS parts:** `base` (the absolutely-positioned overlay, inset 0) and `rect` (one highlight
-rectangle; carries `data-tone`/`data-active`/`data-flash` state attributes).
+**CSS parts:** `base` (the absolutely-positioned overlay, inset 0), `rect` (one visual highlight
+rectangle; carries `data-tone`/`data-active`/`data-flash` state attributes), and `rect-target`
+(transparent activation geometry with a minimum pointer/focus area independent of the visual
+rectangle). When more than one logical highlight would create overlapping minimum hit areas, the
+individual targets are replaced by `highlight-actions` (a non-overlapping action list) containing
+one `highlight-action` button per rendered highlight.
+
+**Themeable custom properties:**
+`--lr-highlight-layer-accent-background`, `--lr-highlight-layer-accent-outline`,
+`--lr-highlight-layer-success-background`, `--lr-highlight-layer-success-outline`,
+`--lr-highlight-layer-warning-background`, `--lr-highlight-layer-warning-outline`,
+`--lr-highlight-layer-danger-background`, `--lr-highlight-layer-danger-outline`,
+`--lr-highlight-layer-neutral-background`, and `--lr-highlight-layer-neutral-outline` control each
+tone independently, defaulting to the corresponding Lyra quiet background and foreground tokens.
+`--lr-highlight-layer-flash-background` controls the temporary flash state (default
+`--lr-color-brand`).
 
 ## `lr-page-rail`
 
@@ -10736,18 +11681,23 @@ shared anchor-target contract).
 
 **Methods:** `search(query)` resolves the match count over cell sources and text outputs — a
 matching cell counts as one match (empty/whitespace query behaves like `clearSearch()`);
-`searchNext()`/`searchPrevious()` advance/step back through matches, scrolling to and flashing the
-target cell; `clearSearch()` clears the query and matches.
+`searchNext()`/`searchPrevious()` advance/step back through matches, scrolling to and marking the
+target cell with the persistent active-cell paint; `clearSearch()` clears the query and matches.
 
 **Events:** `lr-load` — `detail: { cellCount, language }`, fired once a notebook has been parsed
 and validated (`language` from `metadata.language_info.name`/`kernelspec.language`, else `''`).
-`lr-highlight-activate` — `detail: { id }`. `lr-search-change` — `detail: { query, matchCount,
-activeIndex }`. `lr-render-error` — `detail: { error }`, fetching, parsing, or validating the
-notebook failed.
+`lr-search-change` — `detail: { query, matchCount, activeIndex }`. `lr-render-error` —
+`detail: { error }`, fetching, parsing, or validating the notebook failed.
+
+Migration note: the previously declared `lr-highlight-activate` event was never emitted by
+`lr-notebook-viewer` and has been removed from its class/EventMap contract. Use `anchor` plus
+`lr-anchor-result` for notebook cell navigation outcomes.
 
 **CSS parts:** `base` (the root scroll container), `cell` (`data-cell-type="code|markdown|raw"`,
-`data-active`), `cell-active` (added alongside `cell` on the cell an anchor currently targets),
-`cell-gutter` (the `In [n]`/`Out [n]` label column), `cell-source`, `outputs`, `output`
+`data-active`), `cell-active` (added alongside `cell` on the cell currently targeted by an anchor
+or the active search match),
+`cell-gutter` (the `In [n]`/`Out [n]` label column), `cell-source`, `raw-source` (the horizontally
+scrollable preformatted surface for a raw cell), `outputs`, `output`
 (`data-output-type`, `data-stream`), `output-error` (added alongside `output` on a stderr stream or
 an error output), `error-output-label` (the label introducing an error output's traceback),
 `output-toggle`, `error`, `spinner`.
@@ -10762,9 +11712,9 @@ remain on the elements for scripting.
 **Themeable custom properties:** `--lr-notebook-viewer-max-height` (default `none`).
 
 `--lr-notebook-viewer-active-bg` (default `var(--lr-color-brand-quiet)`) is the background of the
-cell currently targeted by an anchor — the `cell-active` part. It is an inline `var()` fallback at
-the point of use rather than a `:host` declaration, so it can be set on the element or on any
-ancestor.
+cell currently targeted by an anchor or the active search match — the `cell-active` part. It is an
+inline `var()` fallback at the point of use rather than a `:host` declaration, so it can be set on
+the element or on any ancestor.
 
 **Optional peer deps:** `marked`+`dompurify` (markdown cells, falls back to plain text per cell),
 `shiki` (code cells, falls back to unhighlighted), `dompurify` (HTML/SVG outputs, falls back to
@@ -10840,10 +11790,12 @@ so lowering it never squashes the chevron below its own box — the visible glyp
 the hit target follows the token, and it can never fall under the accessible minimum from this
 component's own rules.
 
-```html
-<lr-xml-viewer .xml=${payload} collapsed-depth="2" copyable
-  search=${query}
-></lr-xml-viewer>
+```ts
+const viewer = document.querySelector('lr-xml-viewer');
+viewer.xml = payload;
+viewer.collapsedDepth = 2;
+viewer.copyable = true;
+await viewer.search(query);
 ```
 
 Node cap: 50,000 — exceeding it renders the localized `xmlViewerTooManyNodes` error instead of the
@@ -10854,10 +11806,41 @@ tree.
 Comparison surface for two document versions, using `lr-diff-view` for textual diffs and
 `lr-document-preview` for side-by-side rendered content.
 
-**Properties:** `oldVersion`, `newVersion`, `view`, `diffLayout`, `language`, `languages`, `anchor`,
-`copyable`, `syncScroll`. **Events:** `lr-copy`, `lr-download`, `lr-highlight-activate`,
-`lr-render-error`. **CSS parts:** `base`, `diff`, `panes`, `pane-old`, `pane-new`, `pane-header`,
-`pane-empty`. **Themeable custom properties:** `--lr-document-compare-pane-max-height` (default
+**Properties:**
+
+- `oldVersion?: DocumentCompareVersion`, `newVersion?: DocumentCompareVersion` (attribute: false) —
+  the before/after inputs. `DocumentCompareVersion` extends `DocumentRef`
+  (`id`, `name`, `mimeType?`, `uri?`, `version?`) with `text?: string` for diff mode and
+  `highlights?: LyraHighlight[]` for its own preview pane.
+- `view: 'diff' | 'side-by-side' = 'diff'` (reflected) — one inline text diff or two rendered
+  preview panes.
+- `diffLayout: 'unified' | 'split' = 'unified'` (attribute `diff-layout`, reflected) — forwarded
+  to `lr-diff-view` in diff mode.
+- `copyable: boolean = false` — forwards the diff copy action.
+- `language: string = ''`, `languages?: Record<string, ShikiLanguageInput>` (the latter
+  attribute: false) — optional syntax highlighting forwarded to the diff.
+- `syncScroll: boolean = true` (attribute `sync-scroll`) — proportionally mirrors either
+  side-by-side pane's scroll fraction to the other. The true-default converter accepts the literal
+  `sync-scroll="false"`.
+- `anchor: LyraAnchor | string | null = null` (attribute: false) — sends the same target to both
+  preview panes; repeated assignment of the same value still re-runs.
+
+**Exported types:** `DocumentCompareVersion`; `LyraDocumentCompareView = 'diff' |
+'side-by-side'`; `DocumentComparePaneSide = 'old' | 'new'`.
+
+**Synchronized anchors:** activating a region highlight whose id exists in the opposite version
+scrolls that pane to its corresponding highlight, while the original `lr-highlight-activate`
+continues bubbling unchanged. The shared `anchor` property drives both panes. In diff mode, split
+columns already share one scroll container.
+
+**Events:** `lr-copy` (`detail: { text }`), `lr-download` (`detail: { src, filename }`),
+`lr-highlight-activate` (`detail: { id }`), and `lr-render-error` (`detail: { error }`).
+
+**Slots:** none.
+
+**CSS parts:** `base`, `diff`, `panes`, `pane-old`, `pane-new`, `pane-header`, `pane-empty`.
+
+**Themeable custom properties:** `--lr-document-compare-pane-max-height` (default
 `var(--lr-size-24rem)`) — maximum block size of a `side-by-side` pane before it scrolls internally.
 
 ## `lr-geojson-view`
@@ -10878,7 +11861,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.
 
@@ -10890,7 +11876,9 @@ alongside the `lr-json-viewer` fallback), `error` (the error region, `role="aler
 Registered by importing `geojson-view/geojson-view.js` directly — not part of the root barrel, the
 same as `lr-map`/`lr-graph`, since it depends on the same optional `maplibre-gl` peer. Remote
 resources are capped at 25 MB; exceeding it surfaces the localized `documentPreviewResourceTooLarge`
-message instead of the map.
+message instead of the map. MapLibre v6 is ESM-only and requires WebGL2; consumers must import its
+CSS and configure its module-worker URL for their bundler before this viewer constructs the nested
+map. See `llms/components/lr-map.md` for the Vite example and the other bundler variants.
 
 # Conversation & chat UI (`components/conversation/`)
 
@@ -11064,6 +12052,16 @@ restart at the beginning of each visual line, so a wrapped line's tabs land diff
   HTML `marked` produces from `content` completely unsanitized, so untrusted `content` must never be
   paired with `sanitize="false"`.
 
+**Additional API surface:**
+
+- `--lr-markdown-highlight-accent-bg` — Accent highlight fill. Default: `var(--lr-color-brand-quiet)`.
+- `--lr-markdown-highlight-success-bg` — Success highlight fill. Default: `var(--lr-color-success-quiet)`.
+- `--lr-markdown-highlight-warning-bg` — Warning highlight fill. Default: `var(--lr-color-warning-quiet)`.
+- `--lr-markdown-highlight-danger-bg` — Danger highlight fill. Default: `var(--lr-color-danger-quiet)`.
+- `--lr-markdown-highlight-neutral-bg` — Neutral highlight fill. Default: `var(--lr-color-surface)`.
+- `--lr-markdown-highlight-active-bg` — Active highlight fill. Default: `var(--lr-color-brand-quiet)`.
+- `--lr-markdown-highlight-active-outline-color` — Active highlight outline. Default: `var(--lr-color-brand)`.
+
 ---
 
 ## `lr-markdown-core`
@@ -11132,6 +12130,16 @@ differently on a wrapped line.
 </script>
 ```
 
+**Additional API surface:**
+
+- `--lr-markdown-highlight-accent-bg` — Accent highlight fill. Default: `var(--lr-color-brand-quiet)`.
+- `--lr-markdown-highlight-success-bg` — Success highlight fill. Default: `var(--lr-color-success-quiet)`.
+- `--lr-markdown-highlight-warning-bg` — Warning highlight fill. Default: `var(--lr-color-warning-quiet)`.
+- `--lr-markdown-highlight-danger-bg` — Danger highlight fill. Default: `var(--lr-color-danger-quiet)`.
+- `--lr-markdown-highlight-neutral-bg` — Neutral highlight fill. Default: `var(--lr-color-surface)`.
+- `--lr-markdown-highlight-active-bg` — Active highlight fill. Default: `var(--lr-color-brand-quiet)`.
+- `--lr-markdown-highlight-active-outline-color` — Active highlight outline. Default: `var(--lr-color-brand)`.
+
 ---
 
 ## `lr-chat-message`
@@ -11240,6 +12248,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.
@@ -11271,7 +12284,8 @@ between several values across a single element's lifetime.
 - mounting a message with `status="failed"` (or any other non-`"sent"` status) already set does
   **not** announce anything — only a genuine *later* transition (`changed.get('status') !==
   undefined`, i.e. not the very first update) triggers the live-region announcement.
-- `lr-retry` fires with no detail payload at all (`undefined`), not e.g. `{ status: 'failed' }`.
+- `lr-retry` carries `{ messageId?: string }`; the field is the component's `messageId` when set,
+  and is omitted otherwise.
 - the header/footer/avatar/badges/attachments/actions wrappers are shown/hidden via the `hidden`
   attribute, not conditional templating. Whether each slot currently has content is checked once via
   a light-DOM children scan on the very first update (`willUpdate`, gated on `!this.hasUpdated`) and
@@ -11282,6 +12296,20 @@ between several values across a single element's lifetime.
 - `role` intentionally reflects to `data-role`; CSS or selectors that key off role must target
   `[data-role="user"]` etc., not `[role="user"]`.
 
+**Additional API surface:**
+
+- `--lr-chat-message-system-color` — System-message text color. Default: `var(--lr-color-text-quiet)`.
+- `--lr-chat-message-streaming-border-color` — Streaming bubble border. Default: `var(--lr-color-brand)`.
+- `--lr-chat-message-failed-border-color` — Failed bubble border. Default: `var(--lr-color-danger)`.
+- `--lr-chat-message-failed-bg` — Failed bubble fill. Default: `var(--lr-color-danger-quiet)`.
+- `--lr-chat-message-footer-color` — Default footer text. Default: `var(--lr-color-text-quiet)`.
+- `--lr-chat-message-user-footer-color` — User-message footer text. Default: `var(--lr-color-text)`.
+- `--lr-chat-message-failed-footer-color` — Failed-message footer text. Default: `var(--lr-color-danger)`.
+- `--lr-chat-message-indicator-color` — Default status indicator. Default: `var(--lr-color-text-quiet)`.
+- `--lr-chat-message-streaming-indicator-color` — Streaming indicator. Default: `var(--lr-color-brand)`.
+- `--lr-chat-message-failed-indicator-color` — Failed indicator. Default: `var(--lr-color-danger)`.
+- `--lr-chat-message-failed-status-color` — Failed status text. Default: `var(--lr-color-danger)`.
+
 ---
 
 ## `lr-typing-indicator`
@@ -11313,10 +12341,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 +12356,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 +12375,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.
@@ -11546,10 +12578,10 @@ visibility is driven purely by whether anything is slotted into it, not by `phas
 message text color, stalled border), `--lr-color-warning-quiet` (stalled background tint),
 `--lr-space-s` / `--lr-space-xs` (base gap, stalled padding, actions gap), `--lr-radius`
 (base corner radius), `--lr-transition-base` (background/border-color transitions and the
-streaming pulse animation's cycle length). The component also sets two internal, phase-driven
-custom properties (`--lr-stream-status-dot-color`, `--lr-stream-status-dot-opacity`) on
-`:host`, but its own `:host([phase="..."])` rules outrank a page-level override for every phase
-except the default `idle`, so these aren't a practical external theming hook.
+dot's color/opacity transitions), and `--lr-transition-ambient` (the streaming pulse cycle).
+The phase defaults flow through `--lr-stream-status-dot-color` and
+`--lr-stream-status-dot-opacity`; setting either custom property on the element or an ancestor
+wins through the shadow cascade and is the supported per-instance override.
 
 **Optional peer deps:** none.
 
@@ -11674,8 +12706,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 +12726,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 +12914,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`.
@@ -11953,7 +12998,7 @@ of the stream arrives.
 cursor bar's inline size), `--lr-streaming-text-cursor-height` (default `1em`) — both
 component-specific, since no shared "inline cursor bar" token exists, the same pattern
 `<lr-typing-indicator>`'s own `--lr-typing-cursor-width`/`-height` use, plus shared
-`--lr-space-xs` (cursor's `margin-inline-start`) and `--lr-transition-base` (blink animation
+`--lr-space-xs` (cursor's `margin-inline-start`) and `--lr-transition-ambient` (blink animation
 cycle length).
 
 **Optional peer deps:** none — internally imports and auto-registers `<lr-markdown>` for
@@ -12164,8 +13209,7 @@ highlighted HTML, and always fires regardless of whether the actual OS clipboard
 `lr-toggle` (`detail: { collapsed: boolean }` — fired when the built-in collapse/expand header
 button is activated, same event name/shape convention as `<lr-thinking-panel>`'s own `lr-toggle`),
 `lr-line-click` (`detail: { line: number }` — a gutter line number was activated while
-`interactiveLines` is set), `lr-highlight-activate` (`detail: { id: string }` — declared for
-parity with this library's other anchor-target viewers; not currently emitted by this component),
+`interactiveLines` is set),
 `lr-text-select` (`detail: { text, anchor, rects }` — a text selection inside the code body ended;
 `anchor` is a `line-range` anchor covering the selected lines)
 
@@ -12235,10 +13279,11 @@ component's own `part="pre"`/`part="code"` hooks and strips shiki's default `tab
 `<pre>`, since `[part="body"]` is already the single scrollable/focusable region (`role="group"`,
 `tabindex="0"`) for the code area. Dark mode is handled via shiki's own "dual themes" feature: every
 token carries its light color as a plain inline `color`/`background-color` and its dark color in
-`--shiki-dark`/`--shiki-dark-bg` custom properties, which an `!important` media-query rule in
-`code-block.styles.ts` reassigns under `prefers-color-scheme: dark` — the one deliberate exception in
-this component to every other color being a `--lr-*` token, since these values come from shiki's own
-theme data.
+`--shiki-dark`/`--shiki-dark-bg` custom properties. The component watches its resolved Lyra theme
+tokens and sets `data-dark-theme="true"` on the code body when the effective surface is dark; an
+`!important` state rule then activates Shiki's dark values. This follows explicit Lyra theme
+overrides instead of consulting `prefers-color-scheme` directly. Shiki's generated colors are the
+one deliberate exception to every other color being a `--lr-*` token.
 
 **Known gotchas:**
 - `copyable` defaults to `true` and reflects — see the property note above about overriding it with a
@@ -12316,9 +13361,7 @@ Identical behavior to `<lr-code-block>`'s own method.
 highlighted HTML, and always fires regardless of whether the actual OS clipboard write succeeded),
 `lr-toggle` (`detail: { collapsed: boolean }` — fired when the built-in collapse/expand header
 button is activated), `lr-line-click` (`detail: { line: number }` — a gutter line number was
-activated while `interactiveLines` is set), `lr-highlight-activate` (`detail: { id: string }` —
-declared for parity with this library's other anchor-target viewers; not currently emitted by this
-component), `lr-text-select` (`detail: { text, anchor, rects }` — a text selection inside the code
+activated while `interactiveLines` is set), `lr-text-select` (`detail: { text, anchor, rects }` — a text selection inside the code
 body ended; `anchor` is a `line-range` anchor covering the selected lines).
 
 **Slots:** none.
@@ -12502,6 +13545,10 @@ branch content.
 `previous-glyph` and `next-glyph` (the chevron inside each button — target these to swap the
 arrow without restyling the button), and `position` (the visible "2 / 5" text).
 
+**Additional API surface:**
+
+- `click()` — Activates the currently enabled chevron, matching a click on the shadow control.
+
 ## `lr-message-actions`
 
 The per-message action toolbar for `lr-chat-message`'s `actions` slot: opt-in built-ins (copy /
@@ -12626,6 +13673,11 @@ point of use rather than a `:host` declaration, so it can be set on the element
 after `::part()`), so re-pointing the shared `--lr-color-danger` token was previously the only way,
 and it repainted every other danger surface with it.
 
+**Additional API surface:**
+
+- `blur()` — Forwards host blur to the internal push-to-talk control.
+- `focus()` — Forwards host focus to the internal push-to-talk control.
+
 ## `lr-transcript-feed`
 
 Live captions for an in-progress voice session: speaker-grouped entries, interim-vs-final styling
@@ -12884,7 +13936,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`.
 
@@ -13050,7 +14102,8 @@ forced `{ sanitize: true }`), `image` → `lr-media-card` (`src`, `alt`, `filena
 
 **Events:** `lr-widget-action` — `detail: { actionId, payload }`, the single bubbling action
 channel. `lr-render-error` — `detail: { error }`, the root value was structurally unusable
-(non-object, or the depth/size caps made it empty).
+(non-object, or the depth/size caps made it empty). `lr-widget-state-change` — `detail: { path,
+value, nodeId, prop }`, emitted when a state-bound mapped control requests a controlled update.
 
 **CSS parts:** `base` (the root wrapper, `display: contents`), `row`, `col`, `text` (built-in
 structural nodes only — a mapped lyra component exposes its own parts instead).
@@ -13148,6 +14201,18 @@ trigger), `expand-icon`, `empty`, `hint`, `error`.
 - `catalog` must be homogeneous — the same constraint `lr-model-select`'s `LyraModelCatalog` union
   documents.
 
+**Additional API surface:**
+
+- `--lr-voice-picker-preview-active-border` — Active preview border. Default: `var(--lr-color-brand)`.
+- `--lr-voice-picker-preview-active-color` — Active preview icon. Default: `var(--lr-color-brand)`.
+- `--lr-voice-picker-option-active-bg` — Active option fill. Default: `var(--lr-color-brand-quiet)`.
+- `--lr-voice-picker-option-selected-border` — Selected option border. Default: `var(--lr-color-brand)`.
+- `--lr-voice-picker-option-selected-color` — Selected option text. Default: `var(--lr-color-brand)`.
+- `--lr-voice-picker-option-selected-bg` — Selected option fill. Default: `transparent`.
+- `--lr-voice-picker-option-selected-font-weight` — Selected option label weight. Default: `var(--lr-font-weight-semibold)`.
+- `--lr-voice-picker-preview-hover-bg` — Preview hover fill. Default: `var(--lr-color-brand-quiet)`.
+- `--lr-voice-picker-preview-hover-color` — Preview hover icon. Default: `var(--lr-color-brand)`.
+
 ## `lr-agent-workspace`
 
 Responsive, fully controlled shell for an AI conversation and its supporting run, tool, retrieval,
@@ -13246,6 +14311,181 @@ composed `lr-chat-viewport`), `messages`, `messages-empty`, `details`, `details-
 **Optional peer deps:** none of its own; the composed `lr-markdown` keeps its `marked`/`dompurify`
 optional-peer fallback.
 
+## `lr-message-parts`
+
+Ordered renderer for provider-neutral `MessagePart[]`: text, reasoning, tool call/result, citation,
+attachment, data/widget, audio, and error parts can interleave without flattening stream order.
+
+**Properties:** `parts: MessagePart[] = []` (attribute: false); `renderMarkdown: boolean = true`
+(attribute `render-markdown`, reflected) and `showReasoning: boolean = true` (attribute
+`show-reasoning`, reflected), both with string-aware true-default conversion;
+`renderPart?: MessagePartRenderer` (attribute: false), where returning `undefined` delegates that
+part to the built-in renderer; `label: string = ''`; `accessibleLabel: string | null = null`
+(attribute `aria-label`, highest naming precedence).
+
+`MessagePartRenderer = (part: MessagePart, index: number) => unknown`; `MessagePart` and its
+discriminated part shapes come from the `@aceshooting/lyra-ui/ai` subpath.
+
+**Events:** `lr-citation-select` (`{ citation }`), `lr-part-retry` (`{ part }`).
+
+**CSS parts:** `base`, `part`, `part-streaming`, `text`, `reasoning`, `tool-call`, `tool-result`,
+`citation`, `attachment`, `data`, `audio`, `audio-transcript`, `error`, `retry`.
+
+**Slots:** none. **Optional peer deps:** those of composed content only: Markdown can use
+`marked`/`dompurify`, and code content can use `shiki`; every composed primitive retains its own
+fallback.
+
+```ts
+import '@aceshooting/lyra-ui/components/conversation/message-parts/message-parts.js';
+```
+
+**Additional API surface:**
+
+- `lr-anchor-result` event — Passthrough from rendered Markdown.
+- `lr-citation-open` event — Passthrough from a rendered citation's full-preview action.
+- `lr-copy` event — Passthrough from rendered JSON content.
+- `lr-highlight-activate` event — Passthrough from rendered Markdown.
+- `lr-link-click` event — Passthrough from rendered Markdown.
+- `lr-preview` event — Passthrough from a rendered attachment.
+- `lr-remove` event — Passthrough from a rendered attachment.
+- `lr-render-error` event — Passthrough from rendered Markdown, tool-result, or widget content.
+- `lr-retry` event — Passthrough from a rendered attachment.
+- `lr-search-change` event — Passthrough from rendered JSON content.
+- `lr-text-select` event — Passthrough from rendered Markdown.
+- `lr-toggle` event — Passthrough from a rendered reasoning panel.
+- `lr-tool-call-chip-select` event — Passthrough from a rendered tool-call chip.
+- `lr-tool-chip-select` event — Deprecated tool-call selection alias passthrough.
+- `lr-widget-action` event — Passthrough from a rendered declarative widget.
+- `lr-widget-state-change` event — Passthrough from a rendered controlled widget.
+
+## `lr-prompt-input`
+
+The composed prompt surface: chat composer, attachment controls/chips, model and voice pickers,
+retrieval-source scope, mention/slash-command popup, and queued follow-up prompts. It performs no
+upload, retrieval, or model call.
+
+**Properties:** `value: string = ''`; `status: 'idle' | 'sending' | 'streaming' = 'idle'`;
+`placeholder: string = ''`; `disabled: boolean = false` (reflected);
+`submitOnEnter: boolean = true` (attribute `submit-on-enter`, string-aware true-default converter);
+`attachments: PromptInputAttachment[] = []`, `attachmentCapabilities: AttachmentCapability[] =
+['files', 'image', 'audio']`, `mentionItems: PromptSuggestion[] = []`, `commandItems:
+PromptSuggestion[] = []`, `modelCatalog?: LyraModelCatalog`, `voiceCatalog?: LyraVoiceCatalog`,
+`sources: LyraSourceEntry[] = []`, `selectedSourceIds: string[] = []`, and `queue:
+PromptQueueItem[] = []` (all attribute: false); `model: string = ''`; `voice: string = ''`;
+`label: string = ''`; `accessibleLabel: string | null = null` (attribute `aria-label`).
+
+`PromptSuggestion` extends `MentionItem { id, label, description?, icon? }` with optional
+`insertText` (defaults to `label`). `PromptInputAttachment` extends `DocumentRef { id, name,
+mimeType?, uri?, version? }` with `file?`, `size?`, attachment-chip `status?`, and numeric
+`progress?`.
+
+**Methods:** `focus(options?)`, `blur()`, and `click()` forward to the composed chat input;
+`select()` selects its native text surface. `click()` is inert while disabled.
+
+**Events:** `lr-input` (`{ value }`), `lr-submit` (`{ value }`), `lr-stop`,
+`lr-mention-select` (`{ id, label, trigger }`), `lr-attachments-add` (`{ files, capability }`),
+`lr-attachment-remove` (`{ id }`), `lr-model-change`/`lr-voice-change`
+(`{ value, inCatalog }`), `lr-sources-change` (`{ selectedIds }`), `lr-queue-change`
+(`{ items, reason, itemId }`), `lr-send-now` (`{ item }`), `lr-camera-request`,
+`lr-audio-request`, `lr-attachment-retry` (`{ id }`), and `lr-attachment-preview`
+(`{ id, name, mimeType, src }`). Child events are stopped and re-emitted from
+`lr-prompt-input`; all composed interactions are suppressed while `disabled`.
+
+**Slots:** `controls`, `leading`, `chips`, `trailing`, `footer`.
+
+**CSS parts:** `base`, `controls`, `sources`, `sources-summary`, `source-picker`, `queue`,
+`composer`, `leading`, `chips`, `footer`.
+
+**Optional peer deps:** none of its own.
+
+```ts
+import '@aceshooting/lyra-ui/components/conversation/prompt-input/prompt-input.js';
+```
+
+## `lr-prompt-queue`
+
+Controlled editable queue of follow-up turns. Reordering, editing, and removal emit a complete
+proposed queue; send-now emits the complete selected item.
+
+**Properties:** `items: PromptQueueItem[] = []` (attribute: false); `editable: boolean = true`
+(reflected, string-aware true-default converter); `disabled: boolean = false` (reflected);
+`label: string = ''`; `accessibleLabel: string | null = null` (attribute `aria-label`).
+`PromptQueueItem = { id: string; value: string; attachments?: DocumentRef[]; createdAt?: number;
+metadata?: Record<string, unknown> }`.
+
+**Events:** `lr-queue-change` (`PromptQueueChangeDetail = { items, reason, itemId }`, with
+`reason: 'edit' | 'remove' | 'reorder'`), `lr-send-now` (`{ item }`). The queue is controlled:
+these events propose complete next values without mutating `items`.
+
+**CSS parts:** `base`, `heading`, `list`, `item`, `value`, `editor`, `actions`, `action`, `empty`.
+
+**Slots:** none. **Optional peer deps:** none.
+
+```ts
+import '@aceshooting/lyra-ui/components/conversation/prompt-queue/prompt-queue.js';
+```
+
+## `lr-selection-toolbar`
+
+Nonmodal, Escape-dismissible text-selection toolbar carrying selected text plus a format-neutral
+`DocumentLocator` into ask, quote, cite, and copy actions.
+
+**Properties:** `open: boolean = false` (reflected); `text: string = ''`;
+`anchor: DocumentLocator | null = null`, `rect: DOMRectReadOnly | null = null`, and
+`actions: SelectionAction[] = ['ask', 'quote', 'cite', 'copy']` (attribute: false);
+`label: string = ''`; `accessibleLabel: string | null = null` (attribute `aria-label`).
+`SelectionAction = 'ask' | 'quote' | 'cite' | 'copy'`.
+
+**Events:** `lr-selection-action` (`SelectionActionDetail = { action, text, anchor }`);
+`lr-dismiss` (Escape); `lr-copy-error` (`{ error }`). Copy uses the Clipboard API when available;
+the action event still reports the user intent if writing fails, alongside `lr-copy-error`.
+
+**CSS parts:** `toolbar`, `action`, `action-ask`, `action-quote`, `action-cite`, `action-copy`.
+
+**Themeable custom properties:** `--lr-selection-toolbar-inline-start` and
+`--lr-selection-toolbar-block-start` are normally computed from `rect`; hosts may override them to
+provide their own fixed-position anchor.
+
+**Slots:** none. **Optional peer deps:** none.
+
+```ts
+import '@aceshooting/lyra-ui/components/conversation/selection-toolbar/selection-toolbar.js';
+```
+
+**Additional API surface:**
+
+- `--lr-selection-toolbar-inline-shift` — Computed inline collision-avoidance offset.
+- `--lr-selection-toolbar-block-shift` — Computed block collision-avoidance offset.
+
+## `lr-realtime-session`
+
+Provider-neutral realtime voice shell composing connection state, `lr-audio-visualizer`,
+`lr-push-to-talk`, and `lr-transcript-feed`. Transport/authentication/playback remain host-owned.
+
+**Properties:** `state: RealtimeConnectionState = 'disconnected'` (reflected), where the closed set
+is `'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'error'`; `voiceState:
+AudioVisualizerState = 'idle'` (attribute `voice-state`); `level: number | null = null` (finite,
+clamped by the composed visualizer); `stream: MediaStream | null = null` and `entries:
+LyraTranscriptEntry[] = []` (attribute: false); `muted: boolean = false` (reflected);
+`showCapture: boolean = true` (attribute `show-capture`, reflected, string-aware true-default
+converter); `errorCode: string = ''` (attribute `error-code`); `label: string = ''`.
+
+**Events:** `lr-connect`, `lr-disconnect`, `lr-mute-change` (`{ muted }`), `lr-interrupt`; the
+composed push-to-talk events continue bubbling.
+
+**Slots:** `controls` adds provider-specific actions beside the built-in session controls.
+
+**CSS parts:** `base`, `header`, `status`, `activity`, `controls`, `connect`, `disconnect`, `mute`,
+`interrupt`, `capture`, `transcript`, `error`.
+
+**Slots:** `controls` — provider-specific actions appended to the built-in session controls.
+**Optional peer deps:** none. Transport, credentials, capture permission, and media playback
+remain host-owned.
+
+```ts
+import '@aceshooting/lyra-ui/components/conversation/realtime-session/realtime-session.js';
+```
+
 # Agent tooling, tool calls & evaluation (`components/agent-tools/`)
 
 ## `lr-tool-call-chip`
@@ -13300,6 +14540,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 +14611,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 +14660,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 +14682,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 +14762,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"]`
@@ -13582,6 +14875,17 @@ state, so no additional scroll-lock/focus-trap bookkeeping is needed for that tr
 - the `maximize`/`close` buttons are always the first elements in the Tab order while open,
   regardless of visual position, followed by `body` then `footer` content
 
+**Additional API surface:**
+
+- `--lr-tool-result-dialog-running-color` — Running status foreground. Default: `var(--lr-color-brand)`.
+- `--lr-tool-result-dialog-running-bg` — Running status background. Default: `var(--lr-color-brand-quiet)`.
+- `--lr-tool-result-dialog-success-color` — Success status foreground. Default: `var(--lr-color-success)`.
+- `--lr-tool-result-dialog-success-bg` — Success status background. Default: `var(--lr-color-success-quiet)`.
+- `--lr-tool-result-dialog-error-color` — Error status foreground. Default: `var(--lr-color-danger)`.
+- `--lr-tool-result-dialog-error-bg` — Error status background. Default: `var(--lr-color-danger-quiet)`.
+- `--lr-tool-result-dialog-denied-color` — Denied status foreground. Default: `var(--lr-color-warning)`.
+- `--lr-tool-result-dialog-denied-bg` — Denied status background. Default: `var(--lr-color-warning-quiet)`.
+
 ---
 
 ## `lr-tool-select-dialog`
@@ -14231,7 +15535,8 @@ recorded winner, host-writable to reflect a previously-recorded vote back. `item
 (attribute `item-id`) — an opaque id round-tripped through `lr-vote`. `hideTie: boolean = false`
 (attribute `hide-tie`) and `hideBothBad: boolean = false` (attribute `hide-both-bad`) hide the
 corresponding vote button. `syncScroll: boolean = false` (attribute `sync-scroll`) links both panes'
-scroll position.
+scroll position. `disabled: boolean = false` (reflected) disables every vote button and suppresses
+`lr-vote`.
 
 **Slots:** `a` (the first output — any content, a chat message, markdown, a viewer), `b` (the second
 output), and `prompt` (optional shared-input header above both panes).
@@ -14374,6 +15679,11 @@ so retinting one tone doesn't repaint the other surface reading that token, and
 `::part('line')` stylesheet override — the background is applied inline, so a stylesheet rule can't
 beat it without `!important`.
 
+**Additional API surface:**
+
+- `--lr-terminal-search-outline-color` — Outline color for a line containing a non-active search match. Default: `var(--lr-color-warning)`.
+- `--lr-terminal-search-active-outline-color` — Outline color for the active search match's line. Default: `var(--lr-color-brand)`.
+
 ## `lr-trace-tree`
 
 A collapsible span hierarchy for one agent/LLM trace (Langfuse/LangSmith run-tree style): kind icon,
@@ -14421,6 +15731,17 @@ side of the lightness midpoint as the ambient surface, so a consumer who sets
 set `--lr-trace-tree-row-active-color` to match, and should re-check the status-label tones
 against the new tint as well.
 
+**Additional API surface:**
+
+- `--lr-trace-tree-toggle-hover-bg` — Toggle hover background. Default: `var(--lr-color-brand-quiet)`.
+- `--lr-trace-tree-success-color` — Success status text and bar. Default: `var(--lr-color-success)`.
+- `--lr-trace-tree-error-color` — Error status text and bar. Default: `var(--lr-color-danger)`.
+- `--lr-trace-tree-denied-color` — Denied status text and bar. Default: `var(--lr-color-warning)`.
+- `--lr-trace-tree-running-color` — Running status text and stripe. Default: `var(--lr-color-brand)`.
+- `--lr-trace-tree-pending-color` — Pending status text and bar. Default: `var(--lr-color-text-quiet)`.
+- `--lr-trace-tree-bar-track-bg` — Duration bar track. Default: `var(--lr-color-surface-raised)`.
+- `--lr-trace-tree-running-stripe-bg` — Running stripe contrast. Default: `var(--lr-color-brand-quiet)`.
+
 ## `lr-activity-feed`
 
 An append-only streaming log of granular agent actions ("Searching the web…", "Read
@@ -14663,6 +15984,15 @@ viewport's aspect ratio.
 ></lr-browser-frame>
 ```
 
+**Additional API surface:**
+
+- `--lr-browser-frame-controller-background` — Controller badge background. Default: `var(--lr-color-brand-quiet)`.
+- `--lr-browser-frame-controller-color` — Controller badge text color. Default: `var(--lr-color-brand)`.
+- `--lr-browser-frame-ping-click-color` — Click-ping border color. Default: `var(--lr-color-brand)`.
+- `--lr-browser-frame-ping-type-color` — Type-ping border color. Default: `var(--lr-color-success)`.
+- `--lr-browser-frame-ping-scroll-color` — Scroll-ping border color. Default: `var(--lr-color-warning)`.
+- `--lr-browser-frame-ping-move-color` — Move-ping border color. Default: `var(--lr-color-text-quiet)`.
+
 ## `lr-artifact-panel`
 
 Shell around one agent-generated artifact: a title/kind header, a preview↔code toggle, version
@@ -14792,6 +16122,12 @@ is unset. Like the other density/state properties in this family they are inline
 their point of use rather than `:host` declarations, so either can be set on the element *or on any
 ancestor* — one rule on a run list retunes every compact run inside it.
 
+**Additional API surface:**
+
+- `--lr-agent-run-metric-danger-color` — Danger metric value. Default: `var(--lr-color-danger)`.
+- `--lr-agent-run-metric-success-color` — Success metric value. Default: `var(--lr-color-success)`.
+- `--lr-agent-run-metric-warning-color` — Warning metric value. Default: `var(--lr-color-warning)`.
+
 ## `lr-agent-trace`
 
 Provider-neutral agent/LLM trace view combining span-kind filters, handoff quick-jumps, and a
@@ -15064,6 +16400,207 @@ 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"`.
 
+**Additional API surface:**
+
+- `--lr-tool-timeline-running-marker-color` — Running rail dot. Default: `var(--lr-color-brand)`.
+- `--lr-tool-timeline-success-marker-color` — Success rail dot. Default: `var(--lr-color-success)`.
+- `--lr-tool-timeline-error-marker-color` — Error rail dot. Default: `var(--lr-color-danger)`.
+- `--lr-tool-timeline-approved-bg` — Approved badge background. Default: `var(--lr-color-success-quiet)`.
+- `--lr-tool-timeline-approved-color` — Approved badge foreground. Default: `var(--lr-color-success)`.
+- `--lr-tool-timeline-denied-bg` — Denied badge background. Default: `var(--lr-color-danger-quiet)`.
+- `--lr-tool-timeline-denied-color` — Denied badge foreground. Default: `var(--lr-color-danger)`.
+- `--lr-tool-timeline-error-color` — Expanded error text. Default: `var(--lr-color-danger)`.
+
+## `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' }`; `currency:
+string = 'USD'` is the ISO 4217 code used by currency-formatted metrics (invalid codes safely fall
+back to USD). `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 }`, emitted when a metric selector is activated) and
+`lr-run-select` (`{ runId }`).
+
+**CSS parts:** `base`, `heading`, `metrics`, `metric`, `chart`, `runs`, `runs-heading`, `run`,
+`run-label`, `run-meta`, `run-status`, `empty`.
+
+**Additional API surface:**
+
+- `--lr-agent-eval-dashboard-active-border` — Active metric border. Default: `var(--lr-color-brand)`.
+- `--lr-agent-eval-dashboard-active-background` — Active metric background. Default: `var(--lr-color-brand-quiet)`.
+
+## `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`.
+
+**Additional API surface:**
+
+- `--lr-approval-queue-selected-border` — Selected request border. Default: `var(--lr-color-brand)`.
+
+## `lr-mcp-app`
+
+Sandbox host for executable MCP App-style resources. Inline documents run in a unique-origin iframe
+with injected CSP; remote documents are URL-validated. The frame can only request tool calls,
+messages, navigation, logs, and clamped resizing through typed events. Capabilities are denied
+unless explicitly enabled in `resource.permissions`.
+
+**Properties:**
+
+- `resource: McpAppResource | null = null` (attribute: false) — either inline `html` or a safe
+  remote `src`, plus the required logical `uri`. `McpAppResource = { uri: string; title?: string;
+  html?: string; src?: string; csp?: McpAppCsp; permissions?: McpAppPermissions; metadata?:
+  Record<string, unknown> }`. CSP domain arrays accept HTTP(S) origins only. Permissions are
+  optional booleans for camera, microphone, geolocation, clipboard read, and clipboard write.
+- `height: number = 320`, `maxHeight: number = 800` (attribute `max-height`) — requested and maximum
+  frame heights in pixels; runtime values and resize requests clamp to 120–10,000.
+- `label: string = ''`; `accessibleLabel: string | null = null` (attribute `aria-label`) — frame
+  title precedence is host `aria-label`, `label`, resource title, then the localized fallback.
+
+**Methods:** `postHostContext(context: unknown): void` posts host state into the active frame;
+`postToolResult(requestId: string, result?: unknown, error?: string): void` resolves a prior tool
+request. Both are no-ops before a frame exists.
+
+**Exported types:** `McpAppResource`, `McpAppCsp`, `McpAppPermissions`,
+`McpAppToolCallDetail`, and `LyraMcpAppEventMap`.
+
+**Events:** `lr-mcp-ready` (`{ uri }`), `lr-mcp-tool-call` (`{ requestId?, name, args }`),
+`lr-mcp-send-message` (`{ message }`), `lr-mcp-open-link` (`{ href }`), `lr-mcp-log`
+(`{ level, value }`), and `lr-mcp-resize` (`{ height }`). These are host-authorized requests; the
+component does not execute tools, send messages, or navigate itself.
+
+**CSS parts:** `base`, `frame`, `loading`, `error`.
+
+**Slots:** none. **Optional peer deps:** none.
+
+```ts
+import '@aceshooting/lyra-ui/components/agent-tools/mcp-app/mcp-app.js';
+```
+
+## `lr-prompt-studio`
+
+Prompt-development workbench for ordered role messages, `{{variable}}` substitution, saved
+versions, resolved preview, and save/run intents. Message and variable edits update the component's
+current arrays before emitting their complete next state; persistence and execution remain
+host-owned.
+
+**Properties:** `messages: PromptStudioMessage[] = []` and
+`variables: PromptStudioVariable[] = []` are property-only editor state: user edits update the
+current arrays before `lr-change` is emitted, while the host remains responsible for persistence.
+`versions: PromptStudioVersion[] = []` is a property-only host-controlled input;
+`selectedVersionId: string = ''` (attribute `selected-version-id`); `label: string = ''`;
+`running: boolean = false` and `disabled: boolean = false` (both reflected).
+
+**Exported types:** `PromptStudioRole = 'system' | 'user' | 'assistant' | 'tool'`;
+`PromptStudioMessage = { id, role, content, name? }`; `PromptStudioVariable = { name, value,
+description? }`; `PromptStudioVersion = { id: string; label: string; messages:
+PromptStudioMessage[]; variables?: PromptStudioVariable[]; createdAt?: string }`; and
+`PromptStudioState = { messages, variables }`.
+
+**Events:** `lr-change`, `lr-run`, `lr-save` (all carry complete messages/variables);
+`lr-version-select` (`{ version }`).
+
+**CSS parts:** `base`, `toolbar`, `editor`, `messages`, `message`, `message-role`,
+`message-content`, `remove-message`, `add-message`, `variables`, `variable`, `versions`, `version`,
+`preview`, `save`, `run`.
+
+**Slots:** none. **Optional peer deps:** none.
+
+```ts
+import '@aceshooting/lyra-ui/components/agent-tools/prompt-studio/prompt-studio.js';
+```
+
+**Additional API surface:**
+
+- `--lr-prompt-studio-field-hover-border` — Enabled field hover border. Default: `var(--lr-color-brand)`.
+- `--lr-prompt-studio-version-selected-border` — Selected version border. Default: `var(--lr-color-brand)`.
+- `--lr-prompt-studio-version-selected-bg` — Selected version background. Default: `var(--lr-color-brand-quiet)`.
+- `--lr-prompt-studio-version-selected-color` — Selected version foreground. Default: `var(--lr-color-text)`.
+- `--lr-prompt-studio-version-selected-hover-bg` — Selected version hover background. Default: `var(--lr-color-brand-quiet)`.
+
+## `lr-schema-viewer`
+
+Recursive JSON Schema inspector with property/branch selection, required and constraint display,
+validation issues, `$ref` visibility, composition branches, cycle protection, and a depth ceiling.
+It intentionally does not fetch remote references or validate values.
+
+**Properties:** `schema: JsonSchemaNode | null = null` and `issues: SchemaValidationIssue[] = []`
+(attribute: false); `selectedPath: string = ''` (attribute `selected-path`);
+`maxDepth: number = 20` (attribute `max-depth`, clamped to 100); `label: string = ''`.
+
+**Exported types:** `JsonSchemaNode` covers `$ref`, type/title/description, properties/items,
+required/enum/const/default/examples, and oneOf/anyOf/allOf while preserving unknown schema
+keywords. `SchemaValidationIssue = { path: string; message: string; severity?: 'error' | 'warning'
+| 'info' }`.
+
+**Events:** `lr-schema-select` (`{ path, schema }`, with an RFC 6901-style JSON Pointer).
+
+**CSS parts:** `base`, `tree`, `node`, `node-selected`, `node-trigger`, `name`, `type`, `required`,
+`description`, `constraints`, `issue`, `limit`, `empty`.
+
+Rendering is capped at 500 schema nodes; `limit` reports truncation. Cycles stop at the repeated
+node rather than recursing. **Slots:** none. **Optional peer deps:** none.
+
+```ts
+import '@aceshooting/lyra-ui/components/agent-tools/schema-viewer/schema-viewer.js';
+```
+
+**Additional API surface:**
+
+- `part="limit"` — Resource-ceiling status shown when additional nodes are omitted.
+- `--lr-schema-viewer-selected-border` — Selected node branch. Default: `var(--lr-color-brand)`.
+- `--lr-schema-viewer-error-border` — Error issue border. Default: `var(--lr-color-danger)`.
+- `--lr-schema-viewer-error-bg` — Error issue background. Default: `var(--lr-color-danger-quiet)`.
+- `--lr-schema-viewer-warning-border` — Warning issue border. Default: `var(--lr-color-warning)`.
+- `--lr-schema-viewer-warning-bg` — Warning issue background. Default: `var(--lr-color-warning-quiet)`.
+
+## `lr-subagent-panel`
+
+Controlled nested-agent hierarchy with lifecycle badges, task/model context, guarded progress,
+selection, cancel, and retry intents. `SubagentRun.parentId` creates nesting; cycles and orphan
+parents remain renderable instead of recursing forever.
+
+**Properties:** `runs: SubagentRun[] = []` (attribute: false);
+`selectedRunId: string = ''` (attribute `selected-run-id`); `label: string = ''`.
+`SubagentRun = { id: string; parentId?: string; label: string; status: AgentStatusKind; task?:
+string; model?: string; progress?: number; startedAt?: number; endedAt?: number; metadata?:
+Record<string, unknown> }`.
+
+**Events:** `lr-run-select` (`{ run }`), `lr-cancel`/`lr-retry` (`{ runId }`).
+
+**CSS parts:** `base`, `list`, `run`, `run-selected`, `run-row`, `run-trigger`, `label`, `status`,
+`task`, `model`, `progress`, `actions`, `cancel`, `retry`, `limit`, `empty`.
+
+At most 500 runs render, and visual indentation is capped at 12 levels while ARIA hierarchy keeps
+the logical depth. Progress is finite and clamped. **Slots:** none. **Optional peer deps:** none.
+
+```ts
+import '@aceshooting/lyra-ui/components/agent-tools/subagent-panel/subagent-panel.js';
+```
+
+**Additional API surface:**
+
+- `part="limit"` — Resource-ceiling status shown when additional runs are omitted.
+- `--lr-subagent-panel-selected-border` — Selected run border. Default: `var(--lr-color-brand)`.
+- `--lr-subagent-panel-progress-track` — Progress track. Default: `var(--lr-color-border)`.
+- `--lr-subagent-panel-progress-fill` — Progress fill. Default: `var(--lr-color-brand)`.
+
 # Retrieval, knowledge graph & grounding (`components/retrieval/`)
 
 ## `lr-graph`
@@ -15226,9 +16763,9 @@ install with `pnpm add d3-force d3-drag d3-zoom d3-selection`).
   zoom/drag are still pointer-only with no keyboard equivalent. Links (`<line part="link">`) are now
   keyboard-operable too (`tabindex="0"`, `role="button"`, `aria-label`, Enter/Space), matching nodes.
 - while the `d3-force`/`d3-drag`/`d3-zoom`/`d3-selection` peers are resolving, the host shows a
-  `<lr-skeleton>` sized to `width`/`height` with `aria-busy="true"` — but if they fail to load
-  (not installed), it still settles into a permanently empty `<svg>` (0 nodes/0 links) plus a
-  one-time console warning, same as before; the skeleton only covers the loading window itself.
+  `<lr-skeleton>` sized to `width`/`height` with `aria-busy="true"`. If they fail to load (for
+  example, because they are not installed), the graph fails closed with a localized
+  `part="error"` / `role="alert"` message instead of leaving an empty SVG.
 - `GraphNode.color` is sanitized (rejects `;`/`{`/`}`) before being written into the
   `--lr-node-fill` inline custom property, so an untrusted color string can't break out of that
   CSS declaration.
@@ -15754,9 +17291,9 @@ fired after every toggle including select-all).
 
 **CSS parts:** `base`, `search` (the built-in filter `lr-input`, only when `searchable`),
 `select-all` (only when `showSelectAll`), `summary` ("{selected} of {total} selected"), `tree`
-(`role="tree"`), `item` (`role="treeitem"`), `checkbox` (tri-state glyph), `icon` (the
-`lr-file-icon` type badge), `label`, `empty` (`noData` when `sources` is empty, `noMatches` when a
-filter empties the tree).
+(`role="tree"`), `item` (`role="treeitem"`), `disclosure` (a folder row's expand/collapse button),
+`checkbox` (tri-state glyph), `icon` (the `lr-file-icon` type badge), `label`, `empty` (`noData`
+when `sources` is empty, `noMatches` when a filter empties the tree).
 
 **Themeable custom properties:** `--lr-source-picker-checked-bg` — the background of a fully-checked
 selection control: the `select-all` pill (whose resting default is `var(--lr-color-brand-quiet)`) and
@@ -15939,6 +17476,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
@@ -16000,7 +17542,7 @@ direct light-DOM children of the list (plain composition — no `.items` array p
 - `labelPlural: string = ''` (attribute `label-plural`) — fully consumer-built, already-pluralized
   header summary, e.g. `"3 sources"` or `"1 source"`; this component never counts or pluralizes on
   its own. Takes precedence over `label` when both are set. If neither is set, the header falls back
-  to the literal word `"Sources"`.
+  to the localized `sourceListDefaultLabel` string (English default: `"Sources"`).
 
 **Getters:** `sourceCount: number` — read-only, live-updated count of the currently-slotted children,
 handy for building a `label-plural` string reactively, e.g. `` list.labelPlural = `${list.sourceCount} sources` ``.
@@ -16101,10 +17643,9 @@ forwarding scenarios or engines that don't fire `slotchange` for content already
 time.
 
 **Known gotchas:**
-- This library has no built-in i18n/pluralization (the same stance `<lr-empty>`'s plain
-  `description` prop takes) — `lr-source-list`'s header text is entirely consumer-supplied via
-  `label`/`label-plural`; there's no automatic "N sources" string generation beyond the literal
-  `"Sources"` fallback.
+- `lr-source-list` does not automatically build an “N sources” plural summary: provide
+  `labelPlural` when that is wanted. Its no-label fallback is localized through
+  `sourceListDefaultLabel`, and a per-instance `.strings` override reaches the rendered header.
 - `lr-source-card`'s own expand/collapse (`full` slot, `lr-expand` event) is completely
   independent of the parent list's `expanded`/`lr-toggle` — collapsing the list doesn't reset an
   individual card's `fullExpanded` state, and there is no cross-talk between the two components at
@@ -16187,8 +17728,9 @@ and `lr-citation-badge` for each evidence entry.
 **Properties:**
 - `assessment: GroundingAssessment | null = null` (attribute: false) — **`GroundingAssessment`,
   imported from `@aceshooting/lyra-ui/ai`** (`src/ai/types.ts`): `{ supportedClaims: number;
-  unsupportedClaims: number; coverage: number; confidence?: number; warnings?: string[] }`, where
-  `coverage` and `confidence` are 0–1 fractions. `null` renders the empty state
+  unsupportedClaims: number; coverage: number; confidence?: number; warnings?: string[];
+  claims?: GroundedClaim[] }`, where `coverage` and `confidence` are 0–1 fractions. `null` renders
+  the empty state
 - `citations: Citation[] = []` (attribute: false) — **`Citation` from `@aceshooting/lyra-ui/ai`**:
   `{ id: string; chunkId?: string; sourceId?: string; span?: { start: number; end: number };
   label?: string }`. Independent of `assessment`; empty omits the whole evidence section. Each entry
@@ -16198,8 +17740,10 @@ and `lr-citation-badge` for each evidence entry.
   `GroundingSummaryThresholds { high: number; medium: number }` (exported here), both 0–1 fractions,
   applied to both `coverage` and `confidence`: `>= high` → `success` tone, `>= medium` → `warning`,
   below → `danger`
-- `label: string = ''` — accessible group label; falls back to a host `aria-label`, then the
-  localized `groundingSummaryLabel`
+- `label: string = ''` — accessible group label. A host `aria-label` takes precedence, followed by
+  `label`, then the localized `groundingSummaryLabel`
+- `showClaims: boolean = true` (attribute `show-claims`) — renders `assessment.claims` through
+  `lr-claim-evidence`; set false to keep the aggregate scorecard only
 
 **Events:** `lr-citation-select` (`detail: CitationSelectEventDetail` from
 `@aceshooting/lyra-ui/ai` = `{ citation: Citation }`) — emitted when an evidence badge is activated.
@@ -16214,7 +17758,8 @@ row), `warnings` (omitted when there are none), `warnings-heading`, `warnings-co
 `warnings-list` (a `<ul>`), `warning` (one `<li>`), `evidence` (omitted when `citations` is empty),
 `evidence-heading`, `evidence-count`, `evidence-item` (badge + always-visible label/span text),
 `evidence-label` (omitted when `Citation.label` is unset), `evidence-span` (the formatted
-`Citation.span` range, omitted when unset), `empty` (shown when `assessment` is `null`).
+`Citation.span` range, omitted when unset), `claims` (the composed claim-evidence audit), `empty`
+(shown when `assessment` is `null`).
 
 **Themeable custom properties:** shared tokens only.
 
@@ -16260,8 +17805,10 @@ Both `RetryEventDetail` and `CancelEventDetail` come from `@aceshooting/lyra-ui/
 per-item stage label), `item-progress`,
 `item-chunk-count`, `item-embedding-status` (the "N of M chunks embedded" text, only once both
 `chunkCount` and `embeddedChunkCount` are set), `item-attempts` (only once `attempts > 0`),
-`item-error` (only for `stage="failed"` with `error` set), `item-actions`, `retry-button`,
-`cancel-button`, `empty`.
+`item-error` (only for `stage="failed"` with `error` set), `failure-live` (the visually hidden
+assertive region that announces only failures added or transitioned after mount; historical failed
+rows remain visible without being re-announced), `item-actions`, `retry-button`, `cancel-button`,
+`empty`.
 
 In virtualized mode (at or above `virtualizeThreshold`) the rows live in the internal
 `lr-virtual-list`'s shadow root, and `item`, `item-header`, `item-name`, `item-progress`,
@@ -16657,8 +18204,9 @@ fetches, ranks, or computes retrieval results itself.
   stage whose evidence has none of the three renders no disclosure row at all
 - `activeStageId: string | null = null` (attribute `active-stage-id`) — controlled selection,
   forwarded verbatim to the internal `lr-span-waterfall`'s `activeSpanId`
-- `label: string = ''` — accessible name for the timeline; falls back to a host `aria-label`, then
-  the waterfall's own localized default
+- `label: string = ''` — accessible name for the timeline. A host `aria-label` takes precedence,
+  followed by `label`, then the waterfall's own localized default; late attribute changes and
+  removal update that resolved name
 
 **Events:** `lr-stage-select` (`detail: { id: string }`, a stage's bar was activated — click, Enter,
 Space), `lr-stage-toggle` (`detail: { id: string; expanded: boolean }`, an evidence panel was
@@ -16687,3 +18235,142 @@ 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`;
+`showClaims: boolean = true` (attribute `show-claims`); `label: string = ''`; `accessibleLabel:
+string | null = null` (attribute `aria-label`).
+
+**Events:** `lr-citation-select` (`{ citation }`), `lr-claim-select` (`{ claim }`), 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`.
+
+**Themeable custom properties:** `--lr-embedding-explorer-selected-stroke` (default
+`var(--lr-color-brand)`) — stroke color of the selected point. Plus shared tokens.
+
+## `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`.
+
+## `lr-claim-evidence`
+
+Controlled claim-by-claim grounding audit relating `GroundedClaim[]` to complete `Citation[]`
+records. Dangling citation ids are ignored rather than rendered as invented evidence.
+
+**Properties:** `claims: GroundedClaim[] = []` and `citations: Citation[] = []` (attribute: false);
+`selectedClaimId: string = ''` (attribute `selected-claim-id`); `label: string = ''`.
+`GroundedClaim = { id, text, status, citationIds, answerRange?, confidence?, explanation? }`, with
+`status: 'supported' | 'partially-supported' | 'unsupported' | 'contradicted'`. Claim confidence
+is clamped to 0–1 for localized percent display. `Citation` is the shared AI citation record
+(`id`, source/chunk ids, label, locator/ranges, quote, metadata).
+
+**Events:** `lr-claim-select` (`{ claim }`), `lr-citation-select` (`{ citation }`).
+
+**CSS parts:** `base`, `list`, `claim`, `claim-selected`, `claim-trigger`, `status`, `claim-text`,
+`confidence`, `explanation`, `evidence`, `empty`.
+
+Selection is controlled: activation emits the complete claim but does not assign
+`selectedClaimId`. Evidence preserves `citations` order and silently skips dangling ids.
+**Slots:** none. **Optional peer deps:** none.
+
+```ts
+import '@aceshooting/lyra-ui/components/retrieval/claim-evidence/claim-evidence.js';
+```
+
+## `lr-retrieval-compare`
+
+Side-by-side retrieval/reranking workbench showing effective rank, top-k Jaccard overlap, and
+dense/sparse/rerank/final score breakdowns.
+
+**Properties:** `sets: RetrievalComparisonSet[] = []` (attribute: false), where
+`RetrievalComparisonSet = { id: string; label: string; chunks: RetrievalChunk[] }`;
+`topK: number = 10` (attribute `top-k`, finite integer with minimum 1);
+`selectedChunkId: string = ''` (attribute `selected-chunk-id`); `label: string = ''`.
+`RetrievalChunk` is the shared AI record carrying id/text/score/source plus optional rank, locator,
+trace metadata, and `scores?: { dense?, sparse?, rerank?, final }`.
+
+**Events:** `lr-chunk-select` (`{ setId, chunk }`).
+
+**CSS parts:** `base`, `overlap`, `sets`, `set`, `set-heading`, `chunks`, `chunk`,
+`chunk-selected`, `chunk-rank`, `chunk-title`, `chunk-text`, `scores`, `score`, `empty`.
+
+Chunks are ordered by effective rank, then score, then input order before the top-k slice. Overlap
+is pairwise Jaccard similarity across those visible chunk ids. Selection is controlled.
+**Slots:** none. **Optional peer deps:** none.
+
+```ts
+import '@aceshooting/lyra-ui/components/retrieval/retrieval-compare/retrieval-compare.js';
+```
+
+## `lr-rag-eval-dashboard`
+
+Controlled RAG evaluation overview with latest metric cards, per-metric trends, evaluation slices,
+and run history. The host computes metrics and owns evaluation execution.
+
+**Properties:** `metrics: RagEvaluationMetric[] = []` and `runs: RagEvaluationRun[] = []`
+(attribute: false); `metricId: string = ''` (attribute `metric-id`, with the first metric used for
+display when unset/unmatched); `slice: string = ''`; `label: string = ''`;
+`showChart: boolean = true` (attribute `show-chart`, reflected, string-aware true-default
+converter); `chartHeight: string = '220px'` (attribute `chart-height`).
+
+`RagEvaluationMetric = { id, label, category, format? }`, where category is
+`'retrieval' | 'generation' | 'system' | custom-string` and format is `'number' | 'percent'`.
+`RagEvaluationRun = { id, label, metrics: Record<string, number>; slice?, timestamp?, metadata? }`.
+
+**Events:** `lr-metric-change` (`{ metricId }`), `lr-slice-change` (`{ slice }`), and
+`lr-run-select` (`{ run }`). All are controlled intents; the component does not mutate the
+corresponding selection properties.
+
+**CSS parts:** `base`, `heading`, `slices`, `slice`, `slice-selected`, `metrics`, `metric`,
+`metric-selected`, `chart`, `runs`, `runs-heading`, `run`, `empty`.
+
+Percent values clamp to 0–1 and all numbers use `effectiveLocale`. The chart is built from the
+filtered run order; the host computes every metric and owns evaluation execution.
+**Slots:** none. **Optional peer deps:** none.
+
+```ts
+import '@aceshooting/lyra-ui/components/retrieval/rag-eval-dashboard/rag-eval-dashboard.js';
+```
+
+`lr-grounding-summary` and `lr-rag-answer` now accept `GroundingAssessment.claims` and expose
+`showClaims: boolean = true`; `lr-retrieval-results` forwards `RetrievalChunk.locator` as the
+document-viewer-compatible `anchor` in `lr-chunk-open`.