@aceshooting/lyra-ui 6.2.0 → 7.1.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** — 31 tags in `components/agent-tools/`
-- **Retrieval, knowledge graph & grounding** — 27 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,12 +71,27 @@ 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.
 - **Other subpaths.** `@aceshooting/lyra-ui/theme.css` (ready-made light/dark theme),
+  `@aceshooting/lyra-ui/localization.js` (side-effect-free locale runtime),
   `@aceshooting/lyra-ui/ai` (provider-neutral data types), `@aceshooting/lyra-ui/testing`
   (happy-dom shims), `@aceshooting/lyra-ui/internal/*` (shared internals, all documented below).
 
@@ -310,8 +325,12 @@ setLyraTheme({ mode: 'auto', accent: null });    // clears the override and the
 
 **No-flash bootstrap.** `lyraThemeBootstrap` is a self-contained IIFE **string** (not a function),
 meant to be inlined into a `<script>` in `<head>` **before any stylesheet**, so the persisted theme
-is on the root element before first paint. It is a string precisely so this can happen in an
-unbundled `<script>` context without shipping or parsing the module:
+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>
@@ -320,9 +339,9 @@ unbundled `<script>` context without shipping or parsing the module:
 </head>
 ```
 
-It reads the same storage key, applies the same two attributes and `--lr-theme-accent`, and
-swallows any error — malformed storage or a blocked `localStorage` leaves the document untouched
-rather than throwing before your app loads.
+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.
@@ -343,7 +362,10 @@ in the per-component sections:
   overrides, merged over the registered catalog.
 
 ```ts
-import { registerLyraLocale, setLyraLocale } from '@aceshooting/lyra-ui';
+import {
+  registerLyraLocale,
+  setLyraLocale,
+} from '@aceshooting/lyra-ui/localization.js';
 
 registerLyraLocale('fr', { close: 'Fermer', retry: 'Réessayer' }); // app-wide, partial catalogs fine
 setLyraLocale('fr'); // …or just set <html lang="fr"> and let components inherit it
@@ -353,13 +375,16 @@ setLyraLocale('fr'); // …or just set <html lang="fr"> and let components inher
 <lr-toast .strings=${{ close: 'Fermer' }}></lr-toast>
 ```
 
-Exported from the package root: `registerLyraLocale`, `setLyraLocale`, `getLyraLocale`,
-`getRegisteredLyraLocales`, `subscribeLyraLocaleRegistry`, `resolveLyraLocale`,
-`resolveLyraDirection`, `resolveLyraString`, `LYRA_DEFAULT_STRINGS`, and the types
-`LyraLocaleStrings` / `LyraMessageKey`. **`LYRA_DEFAULT_STRINGS` is the authoritative key list**
-(1005 keys, matching the `LyraMessageKey` union) — read it to find the key to override rather than
-guessing one. Lookup falls back exact locale → base language → English. Date, number, byte,
-relative-time and calendar output goes through `Intl`.
+The side-effect-free `@aceshooting/lyra-ui/localization.js` entry exports
+`registerLyraLocale`, `setLyraLocale`, `getLyraLocale`, `getRegisteredLyraLocales`,
+`subscribeLyraLocaleRegistry`, `resolveLyraLocale`, `resolveLyraDirection`, `resolveLyraString`,
+`LYRA_DEFAULT_STRINGS`, and the types `LyraLocaleStrings` / `LyraMessageKey`. The package root
+continues to re-export the same surface for compatibility, but it also registers the non-peer-gated
+component graph; use the dedicated entry when the application only needs locale setup.
+**`LYRA_DEFAULT_STRINGS` is the authoritative key list** (1005 keys, matching the
+`LyraMessageKey` union) — read it to find the key to override rather than guessing one. Lookup
+falls back exact locale → base language → English. Date, number, byte, relative-time and calendar
+output goes through `Intl`.
 
 `getRegisteredLyraLocales(): string[]` lists every locale with strings registered via
 `registerLyraLocale()`, plus `'en'` (always available through the built-in English fallback),
@@ -389,13 +414,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`
@@ -406,15 +447,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
 
@@ -639,8 +700,10 @@ shared `FormAssociated` mixin — see gotchas).
   clear/pick. Forward `options.signal` to `fetch(url, { signal })` to cancel the request when a
   newer query supersedes it or the element disconnects. `loadingText` is shown while a call is in
   flight; a stale in-flight call that resolves after a newer one (or after disconnect) is dropped
-  via a monotonic token. The `options` parameter is optional in the type, so a legacy
-  `(query) => …` source stays assignable.)
+  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)
@@ -857,6 +920,10 @@ synchronous and fires no `input`/`change`/`lr-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`
@@ -901,31 +968,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), 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`.
+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`
 
@@ -1090,9 +1155,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>`
@@ -1219,6 +1286,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
@@ -1304,8 +1381,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`. |
 
@@ -1338,6 +1417,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`
@@ -1387,6 +1470,9 @@ it is neither focusable nor navigable; an unsafe/unparseable `href` falls back t
 - `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).
@@ -1465,9 +1551,17 @@ 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). Host `aria-describedby` targets in the host's root
+  are resolved onto the focused internal control through `ariaDescribedByElements`; external
+  `aria-labelledby` 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
+  with that API expose the relationship through `ariaControlsElements` and intentionally serialize
+  the `aria-controls` content attribute as an empty string. Browsers without the API retain the
+  forwarded string attribute as a best-effort fallback. A reflected element list and a non-empty
+  serialized string cannot coexist; 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.
@@ -1492,6 +1586,15 @@ 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-describedby` targets in the host's own root are resolved through
+`ariaDescribedByElements`. Host `aria-controls` targets use the corresponding
+`ariaControlsElements` 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. Supporting
+browsers intentionally clear each serialized internal IDREF attribute after its explicit element
+list is assigned. Browsers without those APIs retain the forwarded string attributes as
+best-effort fallbacks.
+
 **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.
@@ -1530,11 +1633,15 @@ above 24px — see `llms/shared.md`. `--lr-icon-button-radius` (default `--lr-ra
 `--lr-button-radius` pattern; `lr-icon-button` has no `size` tiers, so there is no per-tier gap
 counterpart to it. `--lr-icon-button-background` (default `transparent`) tints the
 `[part='button']` background, `--lr-icon-button-background-hover` (default `--lr-color-surface`)
-its hover-state background, and `--lr-icon-button-color` (default `inherit`) its icon/text color —
-the same per-component indirection `lr-button`'s `--lr-button-fill`/`--lr-button-on-fill` provide,
-letting you tint a single button without a `::part(button)` rule. Left unset, each falls back to
-today's value, so rendering is unchanged. There is deliberately no border-color token:
-`[part='button']` sets `border: 0`, so a border color could never render.
+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. `--lr-icon-button-border-hover` (default
+`var(--lr-icon-button-border, 0)`) replaces that complete shorthand on hover. 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`
 
@@ -1561,8 +1668,9 @@ 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
@@ -1664,6 +1772,10 @@ Several controls expose the same pair: a per-`size` `*-min-height` **floor**, an
   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
@@ -1828,9 +1940,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'`,
@@ -1937,6 +2049,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`
@@ -1960,6 +2083,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
@@ -1975,8 +2103,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-*`.
 
@@ -2003,10 +2132,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>
 ```
 
@@ -2023,9 +2155,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 —
@@ -2035,12 +2167,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`
@@ -2080,7 +2223,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
@@ -2116,12 +2260,14 @@ and the per-tier `--lr-size-*` tokens.
 </script>
 ```
 
-For the shared gemstone accent mode, import the side-effect-free palette/glyph helper. The
-consumer still owns localized labels, display order, and the initial value:
+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.js';
+import { GEMSTONES } from '@aceshooting/lyra-ui/theme/gemstones-data.js';
 
 const order = ['emerald', 'ruby', 'sapphire', 'hematite'] as const;
 picker.mode = 'gemstone';
@@ -2149,6 +2295,10 @@ picker.value = 'ruby';
 - 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`
@@ -2172,15 +2322,18 @@ 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.
+Host `aria-describedby` targets in the host's own root are resolved onto the internal
+`role="checkbox"` through `ariaDescribedByElements`, so an externally-owned description remains
+valid across the shadow boundary. In supporting browsers the explicit element list intentionally
+leaves the internal role's serialized attribute empty; browsers without the reflected-reference
+API keep the string fallback. The relationship tracks host attribute changes and clears when
+unset.
 
 **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),
@@ -2273,7 +2426,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
@@ -2339,10 +2492,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).
 
@@ -2378,6 +2534,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>
@@ -2396,6 +2553,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.
@@ -2451,16 +2611,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.
@@ -2484,7 +2649,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).
@@ -2493,7 +2660,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
@@ -2527,6 +2695,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
@@ -2588,6 +2767,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
@@ -2604,6 +2788,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
@@ -2633,8 +2824,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
@@ -2693,6 +2886,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
@@ -2702,7 +2902,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.
@@ -2803,6 +3006,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`
@@ -2864,7 +3076,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)
@@ -2956,7 +3169,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`
@@ -2966,8 +3182,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
@@ -3040,6 +3264,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
@@ -3086,7 +3323,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
@@ -3130,7 +3373,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`
@@ -3184,6 +3428,9 @@ 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`,
@@ -3196,12 +3443,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;
@@ -3211,6 +3459,23 @@ 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.
@@ -3222,8 +3487,8 @@ so multiple `sticky` columns stack instead of overlapping; it is a read-out, not
   no `accessibleLabel`/host `aria-label` is present the caption also names the grid via
   `aria-labelledby`.
 - A grid with **none** of `accessibleLabel`, host `aria-label`, or `caption` logs a one-time
-  `console.warn` on first render (dev signal) — an unnamed grid is an accessibility defect that
-  otherwise renders silently.
+  `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
@@ -3346,6 +3611,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`
@@ -3868,9 +4138,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
@@ -3946,9 +4220,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.
@@ -3989,6 +4265,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`
@@ -4016,8 +4298,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
@@ -4096,9 +4380,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.
@@ -4109,6 +4394,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`
@@ -4188,8 +4479,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.
 
@@ -4216,6 +4507,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`
@@ -4367,10 +4663,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
@@ -4384,8 +4682,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.
@@ -4393,6 +4691,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`
@@ -4562,13 +4866,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`.
 
@@ -4584,8 +4903,10 @@ auto-inserted between each adjacent pair.
   omitted/mismatched)
 - `defaultSizes: (number | string)[] = []` (attribute: false) — initialization-only fallback: a
   valid restored `storageKey` layout wins first; otherwise a valid `defaultSizes` wins over equal
-  distribution. Later reassignment never overwrites live drag/persisted state — set it once, at
-  mount. Each entry is either a plain **number** (percent-of-container, validated unchanged: a
+  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
@@ -4826,15 +5147,16 @@ 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
@@ -4917,6 +5239,11 @@ panel'`) and `widgetExpand` (default `'Expand panel'`) keys.
   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.
+
 ---
 
 ## `lr-carousel`
@@ -5118,9 +5445,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:
@@ -5166,19 +5492,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
@@ -5229,9 +5556,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.
 
@@ -5450,6 +5777,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`
@@ -5519,7 +5852,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"`.
@@ -5695,10 +6028,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]`. Set `storageKey` (attribute `storage-key`) to persist `open` and
-`railWidthPx` to `localStorage` under `lr-app-rail:${storageKey}` and restore them on the next mount
-(mirrors `lr-split`'s `storage-key`; `mode` is breakpoint-derived and never persisted). Without a
-`storageKey` there is no persistence — listen for `lr-rail-resize` and persist `widthPx` yourself.
+`[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`
@@ -5743,9 +6079,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 `open` and `railWidthPx` to
-  `localStorage` under `lr-app-rail:${storageKey}` and restores them on the next mount. `mode` is
-  breakpoint-derived and never persisted. Unset means no persistence.
+- `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
@@ -6063,8 +6404,15 @@ 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. In a
+supporting browser, the reflected `ariaControlsElements` list is the source of truth and its setter
+intentionally clears the internal control's serialized `aria-controls` value; browsers without the
+API retain the string as a best-effort fallback), 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
@@ -6192,6 +6540,12 @@ and the open popup also closes it, but deliberately does *not* refocus the trigg
 click itself already moved focus somewhere the user chose.
 
 **Known gotchas:**
+- A supporting browser reports `trigger.shadowRoot`'s focused control
+  `getAttribute('aria-controls') === ''` after the element-reference relationship is assigned.
+  Inspect `ariaControlsElements` instead. This is the platform's reflected-element-reference
+  contract, not a missing menu id; setting the string again would discard the cross-shadow
+  relationship. Browsers without that API keep the string fallback, and `aria-controls` itself is
+  optional for the menu-button pattern.
 - `<lr-menu-item>`'s click handler lives on an inner shadow-DOM element (`[part="base"]`), not the
   host — calling `.click()` directly on the `<lr-menu-item>` host element in a test does **not**
   trigger selection; either click (or dispatch on) the element returned by
@@ -6246,8 +6600,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`,
@@ -6399,6 +6755,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`
@@ -6451,6 +6812,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
@@ -6489,6 +6857,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
@@ -6515,6 +6887,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,
@@ -6533,10 +6909,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
@@ -6611,8 +7002,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`).
@@ -6656,10 +7047,8 @@ at another, since `placement` is a per-call option rather than a single global r
 ```
 
 **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
@@ -6995,16 +7384,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
@@ -7017,16 +7403,21 @@ already follow.
 
 **Events:** `lr-remove` (`detail: { value }` — the remove (×) button was activated via click or
 Enter/Space while focused; only rendered/reachable while `removable`), `lr-chip-select`
-(`detail: { value, selected }` — fired on click, or Enter/Space while focused, when `selected` mode
-is active and `removable` is not set; the chip has already toggled its own `selected` state by the
-time this fires)
+(`detail: { value, selected }` — cancelable; fired from the native toggle button on click or
+Enter/Space with the proposed next state when toggle mode is active and `removable` is not set.
+Calling `preventDefault()` keeps the current `selected` state unchanged)
 
-**Slots:** default (the chip's label content), `icon` (optional leading icon or status dot; nothing
-reserved for it — no extra gap — when left empty)
+**Methods:** `focus(options?)`, `blur()`, and `click()` forward to the active internal control
+(toggle or remove button); a passive chip's `click()` retains ordinary host behavior.
+
+**Slots:** default (the chip's label content; inert in toggle mode, so move links/buttons outside a
+toggleable chip), `icon` (optional leading icon or status dot; nothing reserved for it — no extra
+gap — when left empty)
 
 **CSS parts:** `base` (the pill's root container), `icon` (wrapper around the `icon` slot; hidden
-entirely while empty), `label` (wrapper around the default slot), `remove-button` (the remove (×)
-affordance, only rendered while `removable`)
+entirely while empty), `label` (non-interactive wrapper around the default slot), `toggle-button`
+(the real native toggle control, rendered over the label in toggle mode), `remove-button` (the
+remove (×) affordance, only rendered while `removable`)
 
 **Themeable custom properties:** `--lr-chip-accent`, `--lr-chip-bg`, `--lr-chip-border`
 (component-local trio swapped per `tone` rather than repeating background/color/border per part per
@@ -7158,11 +7549,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.
 
@@ -7206,6 +7599,13 @@ computed-label value so the two can never disagree.
 A click-triggered, light-dismiss floating surface positioned with the shared Floating UI positioner.
 
 **Properties:** `open`, `placement`, `distance`, `accessibleLabel` (`aria-label`), and `popupRole` (`popup-role`).
+The slotted trigger receives `aria-haspopup`, `aria-expanded`, and `aria-controls`.
+`aria-controls` targets the public `lr-popover` host (which receives a stable generated `id` when
+the consumer did not supply one), rather than the shadow-private popup, so the relationship
+resolves from a native light-DOM trigger. `lr-button` and `lr-icon-button` additionally reflect
+that host onto their focused shadow-internal controls through `ariaControlsElements`; supporting
+browsers intentionally serialize the internal control's `aria-controls` content attribute as an
+empty string after that assignment.
 **Methods:** `showAt(rect: { x, y, width?, height?, contextElement? }, options?: { returnFocusTo?:
 HTMLElement })` opens the popover anchored to an arbitrary rectangle instead of the slotted
 `trigger` — for a graph node, a canvas pixel, a chart datum, or any other non-DOM location
@@ -7218,8 +7618,10 @@ the anchor point moves on its own (e.g. a graph pan/zoom tick), re-call `showAt(
 coordinates to re-anchor — the popover stays open across such a call. A popover that never calls
 `showAt()` behaves exactly as before.
 `hide(options?: { focusTrigger?: boolean })` programmatically closes the popover; pass
-`{ focusTrigger: true }` to return focus to the slotted trigger (as Escape does), or omit it to
-close without moving focus (as a bare `el.open = false` does). No-op when already closed.
+`{ 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).
@@ -7241,6 +7643,14 @@ same way any tooltip closes, by setting `open = false`. **Slots:** `trigger`, de
 (default `--lr-size-20rem`), `--lr-tooltip-background` (default `--lr-color-neutral`), and
 `--lr-tooltip-color` (default `--lr-color-on-neutral`).
 
+While open, trigger `aria-describedby` points to a hidden text proxy in the tooltip's light DOM,
+not the shadow-private popup. Native triggers resolve that ID directly. `lr-button` and
+`lr-icon-button` resolve the same proxy onto their focused shadow-internal controls through
+`ariaDescribedByElements`; in supporting browsers that explicit element-reference assignment
+intentionally leaves the internal control's serialized `aria-describedby` value empty. Existing
+author-provided descriptions are merged while open and restored when the trigger is replaced or
+the tooltip disconnects.
+
 **`showAt()` composed with `lr-graph`** — anchoring a popover to a clicked graph node. Note:
 `lr-graph.getNodePosition()` and the `lr-node-click` event's `{ x, y }` are in the graph's own
 *local drawing space* (pre pan/zoom), not viewport pixels, so they can't be passed to `showAt()`
@@ -7268,6 +7678,8 @@ menu-item behavior is needed.
 **Properties:** `open`, `placement`, `distance`, `accessibleLabel` (`aria-label`), and `popupRole` (`popup-role`).
 `popupRole` is seeded to `'menu'` in the constructor — that is the only difference from `lr-popover`,
 whose whole surface (including `showAt()`) is inherited unchanged.
+Its trigger therefore uses the same public-host `aria-controls` target and Lyra-button
+element-reference forwarding described above.
 **Events:** `lr-show`, `lr-hide` — inherited from `lr-popover`; neither fires for the initial render.
 **Slots:** `trigger`, default menu content. **CSS parts:** `trigger`, `popup`, `content`.
 **Themeable custom properties:** `--lr-overlay-max-inline-size` (default `--lr-size-20rem` —
@@ -7304,6 +7716,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`
 
@@ -7384,6 +7802,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`
@@ -7414,12 +7838,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.
 
@@ -7521,6 +7947,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`
@@ -7591,8 +8021,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
@@ -7623,7 +8055,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`.
@@ -7649,9 +8087,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.
 
@@ -7819,10 +8259,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
@@ -7842,18 +8283,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:
@@ -7895,7 +8344,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;
@@ -7905,6 +8360,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) => {
@@ -7915,11 +8371,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
@@ -7931,6 +8387,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.
@@ -7977,6 +8436,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).
@@ -7987,7 +8449,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`/
@@ -8015,13 +8478,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.
 
 ---
 
@@ -8251,6 +8723,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
@@ -8267,6 +8743,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
@@ -8282,7 +8760,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`),
@@ -8290,8 +8769,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**
@@ -8554,6 +9033,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`
@@ -8570,8 +9053,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.
@@ -8682,13 +9165,20 @@ 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` `>=5 <7` (lazy-loaded). The consumer must **separately**
+import `maplibre-gl/dist/maplibre-gl.css`. MapLibre v5's standard build includes its worker.
+MapLibre v6 is ESM-only, requires WebGL2, and additionally needs its module-worker URL configured
+for the bundler once — the component cannot choose a bundler-specific worker URL. For Vite with
+v6:
 
 ```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',
@@ -8702,6 +9192,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`/
@@ -8818,17 +9312,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
@@ -8841,8 +9336,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.
@@ -8873,6 +9367,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`.
@@ -9116,6 +9612,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"`,
@@ -9252,6 +9751,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`
@@ -9371,6 +9874,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.
@@ -9609,12 +10116,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`
 
@@ -9626,8 +10139,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:
@@ -9766,22 +10279,36 @@ Chart.js wrapper every other `lr-*-chart` tag subclasses; supports both a simpli
 - `appendData(label, values, maxPoints?)` — appends one aligned numeric category and optionally
   keeps only the newest `maxPoints`; point-based scatter/bubble series are left unchanged
 
-**Methods:** `resetZoom()` (reset any active zoom/pan to the original view), `refreshTheme()`, and
-`exportData('csv' | 'png')` (returns a spreadsheet-safe CSV snapshot or the current PNG data URL
-when Chart.js is loaded)
-(forces a redraw so the `--lr-chart-*` tokens below are re-read from the current computed style. A
+**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)
+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.
 
-`seriesPalette(): string[]` resolves the categorical series ramp (`--lr-color-chart-1..8`) through
-`getComputedStyle` and returns the concrete, theme-aware colors — the exact same values the chart
-hands any series that sets no `color` of its own. Call it to color chart-adjacent UI (custom
-legends, KPI tiles, annotations fed through the raw `config` passthrough) from one source of truth
-instead of hand-resolving `--lr-color-chart-N` and drifting out of sync when the theme flips.
-Returns a fresh array each call (safe to mutate), and falls back to the light-mode literals only
-when the custom properties can't be resolved at all (e.g. a detached host).
+```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 —
@@ -10171,8 +10698,8 @@ instead of `canvas` when the optional box-plot peer fails to load)
 (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>
@@ -10296,7 +10823,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)
 
@@ -10304,7 +10834,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
@@ -10315,7 +10846,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`.
@@ -10409,10 +10944,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.
 
@@ -10493,6 +11029,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`
@@ -10547,8 +11094,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.
@@ -10648,6 +11195,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.
@@ -10717,6 +11268,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`).
 
@@ -10729,7 +11283,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`.
 
@@ -10916,7 +11474,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.
 
@@ -10949,9 +11507,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
@@ -10996,9 +11556,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
@@ -11054,7 +11616,8 @@ operate on the included text.
   `'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
@@ -11062,9 +11625,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`
 
@@ -11083,8 +11646,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`
 
@@ -11149,18 +11726,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`.
@@ -11175,9 +11757,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
@@ -11253,10 +11835,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
@@ -11267,10 +11851,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`
@@ -11306,7 +11921,10 @@ 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. Lyra supports MapLibre v5 and v6; consumers must import its CSS.
+MapLibre v5's standard build includes its worker, while v6 is ESM-only, requires WebGL2, and needs
+its module-worker URL configured for the bundler before this viewer constructs the nested map. See
+`llms/components/lr-map.md` for the Vite v6 example and the other bundler variants.
 
 # Conversation & chat UI (`components/conversation/`)
 
@@ -11480,6 +12098,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`
@@ -11548,6 +12176,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`
@@ -11692,7 +12330,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
@@ -11703,6 +12342,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`
@@ -11971,10 +12624,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.
 
@@ -12391,7 +13044,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
@@ -12602,8 +13255,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)
 
@@ -12673,10 +13325,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
@@ -12754,9 +13407,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.
@@ -12940,6 +13591,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 /
@@ -13064,6 +13719,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
@@ -13488,7 +14148,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).
@@ -13586,6 +14247,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,
@@ -13684,6 +14357,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`
@@ -14073,6 +14921,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`
@@ -14722,7 +15581,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).
@@ -14865,6 +15725,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,
@@ -14912,6 +15777,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
@@ -15154,6 +16030,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
@@ -15283,6 +16168,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
@@ -15555,23 +16446,41 @@ 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' }`; `runs:
+`{ 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 }`, reserved for host-controlled metric selectors) and
+**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`.
@@ -15587,6 +16496,157 @@ 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`
@@ -15749,9 +16809,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.
@@ -16277,9 +17337,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
@@ -16528,7 +17588,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` ``.
@@ -16629,10 +17689,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
@@ -16715,8 +17774,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
@@ -16726,8 +17786,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.
@@ -16742,7 +17804,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.
 
@@ -16788,8 +17851,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`,
@@ -17185,8 +18250,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
@@ -17225,9 +18291,10 @@ or source fetching.
 **Properties:** `answer: string = ''`; `citations: Citation[] = []` (attribute: false);
 `sources: DocumentRef[] = []` (attribute: false); `assessment: GroundingAssessment | null = null`
 (attribute: false); `loading: boolean = false`; `error: string = ''`; `showSources: boolean = true`;
-`label: string = ''`; `accessibleLabel: string | null = null` (attribute `aria-label`).
+`showClaims: boolean = true` (attribute `show-claims`); `label: string = ''`; `accessibleLabel:
+string | null = null` (attribute `aria-label`).
 
-**Events:** `lr-citation-select` (`{ citation }`) and `lr-retry`.
+**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.
@@ -17249,6 +18316,9 @@ omitted.
 
 **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
@@ -17266,3 +18336,87 @@ 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`.