@aceshooting/lyra-ui 6.2.0 → 7.1.0

package/llms/components/lr-terminal.md

@@ -6,7 +6,7 @@
 - **Class** `LyraTerminal`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/terminal/terminal.class.js`
 - **Family** `components/agent-tools/` — see `llms/index.md` for its siblings
 - **Optional peers** none
-- **Themeable via** 8 parts, 6 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 8 parts, 8 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---
@@ -55,3 +55,8 @@ falls back to (e.g. `accent`'s `--lr-color-brand-quiet` is also the copy/downloa
 so retinting one tone doesn't repaint the other surface reading that token, and from any
 `::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)`.

package/llms/components/lr-textarea.md

@@ -94,8 +94,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`. |
 
@@ -128,4 +130,8 @@ 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.
+
 ---

package/llms/components/lr-time-range.md

@@ -6,7 +6,7 @@
 - **Class** `LyraTimeRange`, also available unregistered from `@aceshooting/lyra-ui/components/forms/time-range/time-range.class.js`
 - **Family** `components/forms/` — see `llms/index.md` for its siblings
 - **Optional peers** none
-- **Themeable via** 7 parts, 4 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 7 parts, 12 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---
@@ -32,6 +32,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
@@ -47,8 +52,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-*`.
 
@@ -75,10 +81,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>
 ```
 
@@ -95,9 +104,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 —
@@ -107,10 +116,21 @@ 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`.
+
 ---

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

@@ -60,8 +60,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`).
@@ -105,10 +105,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

package/llms/components/lr-toast.md

@@ -60,8 +60,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`).
@@ -105,10 +105,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

package/llms/components/lr-token-input.md

@@ -6,7 +6,7 @@
 - **Class** `LyraTokenInput`, also available unregistered from `@aceshooting/lyra-ui/components/forms/token-input/token-input.class.js`
 - **Family** `components/forms/` — see `llms/index.md` for its siblings
 - **Optional peers** none
-- **Themeable via** 10 parts, 7 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 10 parts, 15 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---
@@ -24,7 +24,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).
@@ -33,7 +35,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
@@ -66,3 +69,14 @@ e.g. to pixel-match a sibling field in the same toolbar row), `--lr-token-input-
 inline to `--lr-size-8rem`), `--lr-token-input-min-input-inline-size` (default `--lr-size-4rem`, the
 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)`.

package/llms/components/lr-tool-result-dialog.md

@@ -6,7 +6,7 @@
 - **Class** `LyraToolResultDialog`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/tool-result-dialog/tool-result-dialog.class.js`
 - **Family** `components/agent-tools/` — see `llms/index.md` for its siblings
 - **Optional peers** none
-- **Themeable via** 12 parts, 3 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 12 parts, 11 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---
@@ -104,4 +104,15 @@ 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)`.
+
 ---

package/llms/components/lr-tool-timeline.md

@@ -6,7 +6,7 @@
 - **Class** `LyraToolTimeline`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/tool-timeline/tool-timeline.class.js`
 - **Family** `components/agent-tools/` — see `llms/index.md` for its siblings
 - **Optional peers** none
-- **Themeable via** 15 parts, 4 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 15 parts, 12 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---
@@ -60,3 +60,14 @@ per-entry timeline marker dot's size, which also sets the entry grid's leading c
 retinted independently; `--lr-tool-timeline-pending-approval-border-color` (default
 `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)`.

package/llms/components/lr-tooltip.md

@@ -28,6 +28,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()`

package/llms/components/lr-trace-tree.md

@@ -6,7 +6,7 @@
 - **Class** `LyraTraceTree`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/trace-tree/trace-tree.class.js`
 - **Family** `components/agent-tools/` — see `llms/index.md` for its siblings
 - **Optional peers** none
-- **Themeable via** 16 parts, 2 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 16 parts, 10 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---
@@ -57,3 +57,14 @@ side of the lightness midpoint as the ambient surface, so a consumer who sets
 `--lr-trace-tree-row-active-bg` to a dark tint in light mode (or a light one in dark mode) must
 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)`.

package/llms/components/lr-tree-node.md

@@ -28,9 +28,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
@@ -106,9 +110,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.
@@ -149,4 +155,10 @@ 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[]`.
+
 ---

package/llms/components/lr-tree.md

@@ -28,9 +28,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
@@ -106,9 +110,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.
@@ -149,4 +155,10 @@ 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[]`.
+
 ---

package/llms/components/lr-virtual-list.md

@@ -78,7 +78,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"`.

package/llms/components/lr-voice-picker.md

@@ -6,7 +6,7 @@
 - **Class** `LyraVoicePicker`, also available unregistered from `@aceshooting/lyra-ui/components/conversation/voice-picker/voice-picker.class.js`
 - **Family** `components/conversation/` — see `llms/index.md` for its siblings
 - **Optional peers** none
-- **Themeable via** 16 parts, 0 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 16 parts, 9 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---
@@ -85,3 +85,15 @@ trigger), `expand-icon`, `empty`, `hint`, `error`.
   duplicate (`tabindex="-1"`, `aria-hidden="true"`).
 - `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)`.

package/llms/components/lr-widget-renderer.md

@@ -55,7 +55,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).

package/llms/components/lr-widget.md

@@ -6,7 +6,7 @@
 - **Class** `LyraWidget`, also available unregistered from `@aceshooting/lyra-ui/components/layout/widget/widget.class.js`
 - **Family** `components/layout/` — see `llms/index.md` for its siblings
 - **Optional peers** none
-- **Themeable via** 14 parts, 5 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 16 parts, 5 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---
@@ -34,15 +34,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
@@ -125,4 +126,9 @@ 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.
+
 ---

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

@@ -72,10 +72,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

package/llms/index.md

@@ -2,7 +2,7 @@
 
 # Component index
 
-256 custom elements, grouped by the source family they live in.
+268 custom elements, grouped by the source family they live in.
 
 **Reading one component.** Its reference file path is derived from the tag — no search needed:
 `llms/components/<tag>.md` (e.g. `llms/components/lr-table.md`). Each is self-contained: import
@@ -51,7 +51,7 @@ Optional peers: `llms/peers.md`. `wa-*`/`sl-*` renames: `llms/migration.md`.
 
 - `lr-sparkline` · data/sparkline/sparkline.js — a zero-dependency inline SVG trend chart.
 - `lr-stat` · data/stat/stat.js — a KPI/stat card.
-- `lr-table` · data/table/table.js — a presentational, sort/select-aware data table.
+- `lr-table` · data/table/table.js — a sort/select-aware data table.
 - `lr-pagination` · data/pagination/pagination.js — controlled, server-friendly page navigation with an editable page jump and optional item-range summary.
 - `lr-gauge` · data/gauge/gauge.js — a radial, full-circle ring, or linear meter.
 - `lr-word-cloud` · data/word-cloud/word-cloud.js — a zero-dependency SVG word/tag cloud.
@@ -212,7 +212,7 @@ Optional peers: `llms/peers.md`. `wa-*`/`sl-*` renames: `llms/migration.md`.
 - `lr-document-compare` · viewers/document-compare/document-compare.js — side-by-side or inline comparison of two document versions, composed entirely from two existing primitives rather than reimplementing eit...
 - `lr-geojson-view` · viewers/geojson-view/geojson-view.js — internal document-registry bridge rendering a fetched GeoJSON file through `<lr-map>`'s `dataLayers`.
 
-## Conversation & chat UI — `components/conversation/` (28)
+## Conversation & chat UI — `components/conversation/` (33)
 
 - `lr-markdown` · conversation/markdown/markdown.js — sanitized Markdown-to-HTML rendering (GFM tables, fenced code blocks, links, blockquotes) built on the optional peer dependencies `marked...
 - `lr-markdown-core` · conversation/markdown/markdown-core.js — a build-lean variant of `<lr-markdown>` for a consumer whose `languages` map already covers every language it will ever render.
@@ -242,8 +242,13 @@ Optional peers: `llms/peers.md`. `wa-*`/`sl-*` renames: `llms/migration.md`.
 - `lr-widget-renderer` · conversation/widget-renderer/widget-renderer.js — renders an agent-streamed declarative JSON widget tree through an allowlisted `type -> lyra tag` registry (see `registry.ts`/`resolve.ts`...
 - `lr-voice-picker` · conversation/voice-picker/voice-picker.js — a TTS voice selector over a host-supplied `catalog`, mirroring `lr-model-select`'s closed-dropdown/free-text-combobox dual mode, stale-va...
 - `lr-agent-workspace` · conversation/agent-workspace/agent-workspace.js — a responsive, controlled shell for an AI conversation and its supporting agent state.
+- `lr-message-parts` · conversation/message-parts/message-parts.js — renders ordered, interleavable provider-neutral AI message parts.
+- `lr-prompt-input` · conversation/prompt-input/prompt-input.js — a composed AI prompt surface combining the chat composer with attachments, model and voice selection, retrieval sources, mentions, slash...
+- `lr-prompt-queue` · conversation/prompt-queue/prompt-queue.js — a controlled queue of follow-up prompts that can be edited, reordered, removed, or sent immediately while another agent turn is active.
+- `lr-selection-toolbar` · conversation/selection-toolbar/selection-toolbar.js — a nonmodal action toolbar positioned above selected text.
+- `lr-realtime-session` · conversation/realtime-session/realtime-session.js — a provider-neutral voice-session shell composing connection status, live activity, transcript, native capture, mute, interruption, and co...
 
-## Agent tooling, tool calls & evaluation — `components/agent-tools/` (31)
+## Agent tooling, tool calls & evaluation — `components/agent-tools/` (35)
 
 - `lr-tool-call-chip` · agent-tools/tool-call-chip/tool-call-chip.js — a compact inline pill representing one tool/ function call an agent made mid-conversation, e.g.
 - `lr-tool-result-view` · agent-tools/tool-result-view/tool-result-view.js — renders a tool call's result via whichever custom renderer a host app has registered for it (see `registerToolRenderer()` in `registry.ts...
@@ -276,8 +281,12 @@ Optional peers: `llms/peers.md`. `wa-*`/`sl-*` renames: `llms/migration.md`.
 - `lr-tool-timeline` · agent-tools/tool-timeline/tool-timeline.js — a chronological list of an agent run's tool/function calls, each rendered through `<lr-tool-call-chip>` (name/status/duration) and `<lr-t...
 - `lr-agent-eval-dashboard` · agent-tools/agent-eval-dashboard/agent-eval-dashboard.js — a controlled evaluation overview with metric cards, a trend chart, and run-status history.
 - `lr-approval-queue` · agent-tools/approval-queue/approval-queue.js — a controlled queue of tool calls that need human approval, with a keyboard-accessible request list and a single reused `<lr-tool-approval...
+- `lr-mcp-app` · agent-tools/mcp-app/mcp-app.js — hosts an MCP App-style executable UI resource in a uniquely-origin sandbox.
+- `lr-prompt-studio` · agent-tools/prompt-studio/prompt-studio.js — a provider-neutral prompt-development workbench for ordered role messages, `{{variable}}` substitution, version selection, preview, save,...
+- `lr-schema-viewer` · agent-tools/schema-viewer/schema-viewer.js — a recursive, selectable JSON Schema inspector with required-state, constraints, composition branches, `$ref` display, validation issues,...
+- `lr-subagent-panel` · agent-tools/subagent-panel/subagent-panel.js — a controlled hierarchy of nested agent runs with lifecycle status, task/model context, progress, selection, cancellation, and retry intents.
 
-## Retrieval, knowledge graph & grounding — `components/retrieval/` (27)
+## Retrieval, knowledge graph & grounding — `components/retrieval/` (30)
 
 - `lr-graph` · retrieval/graph/graph.js — a force-directed node-link diagram with pan/zoom/drag.
 - `lr-node-palette` · retrieval/node-palette/node-palette.js — the searchable, categorized node library for workflow editors: drag an item onto a canvas, or place it by keyboard.
@@ -306,3 +315,6 @@ Optional peers: `llms/peers.md`. `wa-*`/`sl-*` renames: `llms/migration.md`.
 - `lr-rag-answer` · retrieval/rag-answer/rag-answer.js — a controlled grounded-answer surface combining sanitized Markdown, citation badges, a grounding assessment, and source previews.
 - `lr-embedding-explorer` · retrieval/embedding-explorer/embedding-explorer.js — a dependency-free, accessible 2D embedding projection viewer.
 - `lr-knowledge-base-admin` · retrieval/knowledge-base-admin/knowledge-base-admin.js — a responsive operations shell composing the existing controlled source inventory and ingestion queue into one tabbed knowledge-base view.
+- `lr-claim-evidence` · retrieval/claim-evidence/claim-evidence.js — a controlled claim-by-claim grounding audit.
+- `lr-retrieval-compare` · retrieval/retrieval-compare/retrieval-compare.js — a side-by-side retrieval/reranking workbench that makes rank, overlap, and dense/sparse/rerank/final score changes inspectable.
+- `lr-rag-eval-dashboard` · retrieval/rag-eval-dashboard/rag-eval-dashboard.js — a controlled RAG quality overview with current metric cards, per-metric trends, evaluation slices, and run history.