@aceshooting/lyra-ui 6.1.0 → 7.0.0

package/llms/components/lr-textarea.md

@@ -6,6 +6,7 @@
 - **Class** `LyraTextarea`, also available unregistered from `@aceshooting/lyra-ui/components/forms/textarea/textarea.class.js`
 - **Family** `components/forms/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 5 parts, 1 custom property — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---
@@ -40,10 +41,29 @@ submission/validation/reset via `name`/`value`/`disabled`/`required`/`checkValid
 | `autocomplete` | `autocomplete` | `string` | `''` | Forwarded to the native `<textarea>`; empty omits the attribute. |
 | `inputMode` | `inputmode` | `string` | `''` | Virtual-keyboard input hint forwarded to the native `<textarea>`. |
 | `enterKeyHint` | `enterkeyhint` | `string` | `''` | Virtual-keyboard Enter-key hint forwarded to the native `<textarea>`. |
+| `minlength` | `minlength` | `number \| undefined` | `undefined` | Minimum text length; forwarded to the native `<textarea>` and reported as `validity.tooShort`. |
+| `maxlength` | `maxlength` | `number \| undefined` | `undefined` | Maximum text length; forwarded to the native `<textarea>` (which also stops typing past it) and reported as `validity.tooLong`. |
 | `name` | `name` | `string` | `''` | Form field name. |
 | `disabled` | `disabled` | `boolean` | `false` | Disables the control. |
 | `required` | `required` | `boolean` | `false` | Participates in native constraint validation. |
 
+### Constraint validation
+
+`validity` reports `valueMissing` (from `required`), `tooShort` (from `minlength`), and `tooLong`
+(from `maxlength`) — the complete set a native `<textarea>` can produce. Leaving `minlength` and
+`maxlength` unset constrains nothing, exactly as before they existed.
+
+Two behaviors are worth knowing, both inherited from the platform and both shared with `lr-input`:
+
+- **An empty value is never `tooShort`.** Native `minlength` only applies to a non-empty value, so
+  an optional field left blank stays valid; `required` is what rejects empty.
+- **A script-assigned value is validated too.** The native `tooShort`/`tooLong` flags are raised
+  only for a value the *user* edited, so the component recomputes both from its own `value` and
+  ORs them in — `el.value = <over-length>` reports `tooLong` rather than silently submitting.
+  Lengths count UTF-16 code units, matching the native control (one emoji counts as two).
+  `validationMessage` is the browser's own localized message when the native control flagged the
+  value, and the localized `valueInvalid` string when only the script-value check did.
+
 The visible label, hint, and error live in the same shadow tree as the native control, so their
 generated ids safely drive the native `<label>`/`aria-describedby` relationships. Name precedence
 is `accessibleLabel`/host `aria-label`, visible `label`, `placeholder`, then the localized
@@ -74,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`. |
 
@@ -108,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-thinking-panel.md

@@ -6,6 +6,7 @@
 - **Class** `LyraThinkingPanel`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/thinking-panel/thinking-panel.class.js`
 - **Family** `components/agent-tools/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 6 parts, 1 custom property — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---

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

@@ -6,6 +6,7 @@
 - **Class** `LyraThreadList`, also available unregistered from `@aceshooting/lyra-ui/components/conversation/thread-list/thread-list.class.js`
 - **Family** `components/conversation/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 32 parts, 0 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---
@@ -109,7 +110,7 @@ reach callback-rendered descendants through these parts). `row-excerpt` wraps `r
 output, which is slotted into the row item's own `excerpt` slot.
 
 Data mode additionally forwards each row `<lr-conversation-item>`'s own parts under a `row-item-`
-prefix: `row-item-base`, `row-item-option`, `row-item-leading`, `row-item-content`,
+prefix: `row-item-base`, `row-item-active-indicator`, `row-item-option`, `row-item-leading`, `row-item-content`,
 `row-item-title`, `row-item-title-input`, `row-item-rename-button`, `row-item-excerpt`,
 `row-item-meta`, `row-item-timestamp`, `row-item-actions`.
 

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

@@ -6,6 +6,7 @@
 - **Class** `LyraTimeInput`, also available unregistered from `@aceshooting/lyra-ui/components/forms/input/time-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
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---
@@ -19,8 +20,9 @@ re-typed `min`/`max` pair (below); every other property, event, slot and part is
 **Properties:** `size` (`2xs`…`xl`), `placeholder`, `readonly`, `label`, `hint`, `errorText`
 (`error-text`), `accessibleLabel` (`aria-label`), `autocomplete`, `spellcheck`, `autocapitalize`,
 `autoCorrect` (`autocorrect`), `inputMode` (`inputmode`), and `enterKeyHint` (`enterkeyhint`).
-`clearable` and `passwordVisible` (`password-visible`) are inherited but inert, exactly as on
-`lr-number-input`.
+`clearable`, `passwordVisible` (`password-visible`), and `minlength`/`maxlength`/`pattern` are
+inherited but inert, exactly as on `lr-number-input` — the platform ignores all three length/pattern
+constraints on `type="time"` as well.
 
 `step` is forwarded verbatim to the native time input, where it means seconds (`step="1"` reveals
 the seconds field, `'any'` disables step validation).

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

@@ -6,6 +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, 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`
 
 ---
@@ -31,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
@@ -46,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-*`.
 
@@ -74,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>
 ```
 
@@ -94,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 —
@@ -106,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-timeline-item.md

@@ -6,6 +6,7 @@
 - **Class** `LyraTimelineItem`, also available unregistered from `@aceshooting/lyra-ui/components/data/timeline/timeline-item.class.js`
 - **Family** `components/data/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 9 parts, 9 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Documented with** `lr-timeline` (same section below)
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 

package/llms/components/lr-timeline.md

@@ -6,6 +6,7 @@
 - **Class** `LyraTimeline`, also available unregistered from `@aceshooting/lyra-ui/components/data/timeline/timeline.class.js`
 - **Family** `components/data/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 1 part, 1 custom property — see this component's own `@csspart`/`@cssprop` list below
 - **Documented with** `lr-timeline-item` (same section below)
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 

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

@@ -6,6 +6,7 @@
 - **Class** `LyraToastItem`, also available unregistered from `@aceshooting/lyra-ui/components/overlays/toast/toast-item.class.js`
 - **Family** `components/overlays/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 5 parts, 6 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Documented with** `lr-toast` (same section below)
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
@@ -59,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`).
@@ -83,7 +84,7 @@ From the `toaster` controller — the ergonomic entry point, no manual `<lr-toas
 needed:
 
 ```ts
-import { toast } from '@aceshooting/lyra-ui';
+import { toast } from '@aceshooting/lyra-ui/components/overlays/toast/toaster.js';
 
 toast('Saved');
 toast({ message: 'Deleted', variant: 'danger', action: { label: 'Undo', onClick: (item) => {/*...*/} } });
@@ -98,16 +99,14 @@ at another, since `placement` is a per-call option rather than a single global r
 
 ```html
 <script type="module">
-  import { toast } from '@aceshooting/lyra-ui';
+  import { toast } from '@aceshooting/lyra-ui/components/overlays/toast/toaster.js';
   document.getElementById('save-btn').addEventListener('click', () => toast('Saved!'));
 </script>
 ```
 
 **Known gotchas:**
-- possible nested live-region double-announcement: the stack region is
-  `role="status" aria-live="polite"` **and** each `lr-toast-item` independently self-assigns its
-  own `role` (`status`/`alert`) — nesting live regions can cause some screen readers to announce a
-  new toast twice. Plausible from the code, unverified against real AT.
+- the stack itself has no live-region role; each `lr-toast-item` owns the single `status`/`alert`
+  role appropriate to its current variant, avoiding nested live-region announcements.
 - the close button's accessible name is derived from the toast's own message text (`"Close: <first
   40 chars>…"`, falling back to bare `"Close"` only when the toast has no text content) rather than
   a bare `"Close"` on every instance — useful when several toasts are stacked and a screen-reader or

package/llms/components/lr-toast.md

@@ -6,6 +6,7 @@
 - **Class** `LyraToast`, also available unregistered from `@aceshooting/lyra-ui/components/overlays/toast/toast.class.js`
 - **Family** `components/overlays/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 1 part, 8 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Documented with** `lr-toast-item` (same section below)
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
@@ -59,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`).
@@ -83,7 +84,7 @@ From the `toaster` controller — the ergonomic entry point, no manual `<lr-toas
 needed:
 
 ```ts
-import { toast } from '@aceshooting/lyra-ui';
+import { toast } from '@aceshooting/lyra-ui/components/overlays/toast/toaster.js';
 
 toast('Saved');
 toast({ message: 'Deleted', variant: 'danger', action: { label: 'Undo', onClick: (item) => {/*...*/} } });
@@ -98,16 +99,14 @@ at another, since `placement` is a per-call option rather than a single global r
 
 ```html
 <script type="module">
-  import { toast } from '@aceshooting/lyra-ui';
+  import { toast } from '@aceshooting/lyra-ui/components/overlays/toast/toaster.js';
   document.getElementById('save-btn').addEventListener('click', () => toast('Saved!'));
 </script>
 ```
 
 **Known gotchas:**
-- possible nested live-region double-announcement: the stack region is
-  `role="status" aria-live="polite"` **and** each `lr-toast-item` independently self-assigns its
-  own `role` (`status`/`alert`) — nesting live regions can cause some screen readers to announce a
-  new toast twice. Plausible from the code, unverified against real AT.
+- the stack itself has no live-region role; each `lr-toast-item` owns the single `status`/`alert`
+  role appropriate to its current variant, avoiding nested live-region announcements.
 - the close button's accessible name is derived from the toast's own message text (`"Close: <first
   40 chars>…"`, falling back to bare `"Close"` only when the toast has no text content) rather than
   a bare `"Close"` on every instance — useful when several toasts are stacked and a screen-reader or

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

@@ -6,6 +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, 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`
 
 ---
@@ -23,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).
@@ -32,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
@@ -65,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-approval-dialog.md

@@ -6,6 +6,7 @@
 - **Class** `LyraToolApprovalDialog`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/tool-approval-dialog/tool-approval-dialog.class.js`
 - **Family** `components/agent-tools/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 22 parts, 2 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---

package/llms/components/lr-tool-call-chip.md

@@ -6,6 +6,7 @@
 - **Class** `LyraToolCallChip`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/tool-call-chip/tool-call-chip.class.js`
 - **Family** `components/agent-tools/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 10 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`
 
 ---
@@ -62,6 +63,11 @@ referenced: `--lr-color-text-quiet`, `--lr-color-surface`, `--lr-color-border`,
 `--lr-space-xs/-s/-m`, `--lr-radius`, `--lr-shadow`, `--lr-focus-ring-*`,
 `--lr-transition-fast`.
 
+> Retheming a chip from outside `<lr-tool-call-chip>` (e.g. per-tool or per-status colors)?
+> Set `--lr-theme-*` on the ancestor wrapper, not `--lr-*` directly — see `llms/shared.md`'s
+> "Theming and design tokens" section for why a `--lr-*` override on a wrapper only reaches that
+> wrapper's *direct* children, not a nested `<lr-*>` host's shadow DOM.
+
 **Optional peer deps:** none.
 
 ```html

package/llms/components/lr-tool-param-form.md

@@ -6,6 +6,7 @@
 - **Class** `LyraToolParamForm`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/tool-param-form/tool-param-form.class.js`
 - **Family** `components/agent-tools/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 7 parts, 0 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---

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

@@ -6,6 +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, 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`
 
 ---
@@ -103,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-result-view.md

@@ -6,6 +6,7 @@
 - **Class** `LyraToolResultView`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/tool-result-view/tool-result-view.class.js`
 - **Family** `components/agent-tools/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 3 parts, 1 custom property — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---
@@ -38,6 +39,13 @@ shell around it.
 - `copyable: boolean = false` (reflected) — shows a copy-to-clipboard affordance alongside the
   fallback view, for either `fallback` kind: forwarded to `<lr-json-viewer>`'s own `copyable` for
   `"json"`, or a `<lr-copy-button>` rendered next to the text for `"text"`.
+- `status: 'pending'|'running'|'success'|'error'|'denied' = 'success'` (reflected) — the outcome of
+  the currently-rendered result, as reported by the matched renderer's own `context.reportStatus()`
+  (see below). Reset to `'success'` immediately before every `render()` call, so a renderer that
+  never calls `reportStatus` — including every pre-existing 2-arg renderer written before this
+  property existed — leaves it at that default, and a later renderer that stays quiet doesn't
+  inherit a stale outcome left behind by a previous one. Same status vocabulary as
+  `<lr-tool-result-dialog>`/`<lr-tool-call-chip>`.
 
 **Events:** `lr-render-error` (`detail: { toolName: string; error: unknown }`) — fired immediately
 before falling back to `<lr-json-viewer>`, whether because no renderer matched, a candidate
@@ -80,10 +88,16 @@ this same module-level registry unless a given `<lr-tool-result-view>`'s `regist
 set to a different `Map` instance.
 
 **`ToolRendererDefinition`** — the shape of one registered renderer:
-- `render?: (result: unknown, args: unknown) => unknown` — renders the result (and the args that
-  produced it) as UI. Typed as `unknown` rather than Lit's `TemplateResult` so any lit-html-renderable
-  value works (a plain string, a DOM node, an array of templates) — consumers already own their own
-  Lit import and don't need this module to add one
+- `render?: (result: unknown, args: unknown, context: ToolRenderContext) => unknown` — renders the
+  result (and the args that produced it) as UI. Typed as `unknown` rather than Lit's
+  `TemplateResult` so any lit-html-renderable value works (a plain string, a DOM node, an array of
+  templates) — consumers already own their own Lit import and don't need this module to add one.
+  The 3rd `context` argument is additive: it's the *last* positional parameter, so a pre-existing
+  2-arg `render(result, args)` function stays assignable to this type unchanged — JS/TS function
+  assignability allows an implementation with fewer parameters than its declared type. Use
+  `context.reportStatus(status)` (see `ToolRenderContext` below) to signal a non-throwing outcome
+  — e.g. an application-level failure the renderer still drew real UI for — instead of throwing,
+  which discards that UI for the `<lr-json-viewer>` fallback instead
 - `matches?: (payload: unknown) => boolean` — facade/shape-based dispatch predicate, consulted only
   when no exact `toolName` key matches (see dispatch order below); only ever consulted *before*
   `load` resolves when supplied inline at registration time — a definition that needs shape-based
@@ -96,6 +110,27 @@ set to a different `Map` instance.
   object, so `load: () => import('./my-renderer.js')` works unmodified when that module's default
   export is itself a `ToolRendererDefinition`
 
+**`ToolRenderContext`** — the shape of `render()`'s 3rd argument:
+- `reportStatus: (status: ToolResultStatus) => void` — reports this render's outcome without
+  throwing. `ToolResultStatus` is `'pending' | 'running' | 'success' | 'error' | 'denied'`, the same
+  union `<lr-tool-result-dialog>`/`<lr-tool-call-chip>` use, re-exported from this module. Calling
+  it is entirely optional: a renderer that never calls it leaves `<lr-tool-result-view>`'s `status`
+  property at its default, `'success'`. This threads through the lazy `load()` path exactly the
+  same way — a `render()` resolved via `load()` receives the same 3rd `context` argument as one
+  registered directly.
+
+```ts
+registerToolRenderer('run_query', {
+  render: (result, _args, context) => {
+    if ((result as { rows?: unknown[] })?.rows === undefined) {
+      context.reportStatus('error');
+      return html`<p class="query-error">The query returned no result set.</p>`;
+    }
+    return html`<query-result-table .rows=${(result as { rows: unknown[] }).rows}></query-result-table>`;
+  },
+});
+```
+
 **Exports:**
 - `registerToolRenderer(name: string, def: ToolRendererDefinition): void` — registers (or
   overwrites) the renderer for `name` in the module-level default registry
@@ -155,6 +190,20 @@ registerToolRenderer('web_search', {
 - `matches` is a linear scan over every registered definition's `matches` in registration order; it
   only runs when the exact-name lookup misses, so tool names with a direct registration never pay
   that scan cost
+- `status` is reset to `'success'` immediately before every `render()` call, not merely at
+  construction — a renderer that reported `'error'` on one result does not leave that status
+  behind once dispatch moves on to a different (quiet) renderer; a `reportStatus()` call that
+  arrives asynchronously after a *newer* resolve has already started (a stale promise the previous
+  render kicked off) is detected via the same generation counter as the `load()` staleness guard
+  and discarded rather than clobbering the newer status
+- **don't type a custom renderer against a hand-rolled, over-generic function signature** (e.g.
+  `render: (...args: any[]) => unknown`, or a locally-declared narrower alias then cast to
+  `ToolRendererDefinition`) — write the registration as a plain object literal (as in every example
+  above) or annotate it as `ToolRendererDefinition` directly, so TypeScript checks the actual
+  current `render`/`matches`/`load` shape, including the `context: ToolRenderContext` 3rd
+  parameter and the exact `ToolResultStatus` string union `reportStatus` accepts. A loosened/`any`
+  signature type-checks either way but silently gives up the compiler's ability to catch a typo'd
+  status string or a dropped `context` parameter
 - `fallback` implements exactly two kinds, `"json"` and `"text"`; any *other* value silently behaves
   as `"json"`, as does `"text"` whenever `result` isn't a string. Only `"text"` renders
   `[part="fallback-text"]`/`[part="fallback-copy"]`

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

@@ -6,6 +6,7 @@
 - **Class** `LyraToolSelectDialog`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/tool-select-dialog/tool-select-dialog.class.js`
 - **Family** `components/agent-tools/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 23 parts, 1 custom property — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---

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

@@ -6,6 +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, 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`
 
 ---
@@ -59,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

@@ -6,6 +6,7 @@
 - **Class** `LyraTooltip`, also available unregistered from `@aceshooting/lyra-ui/components/overlays/overlay/tooltip.class.js`
 - **Family** `components/overlays/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 2 parts, 3 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---

package/llms/components/lr-tour.md

@@ -6,6 +6,7 @@
 - **Class** `LyraTour`, also available unregistered from `@aceshooting/lyra-ui/components/utility/tour/tour.class.js`
 - **Family** `components/utility/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 12 parts, 6 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---

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

@@ -6,6 +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, 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`
 
 ---
@@ -56,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-transcript-feed.md

@@ -6,6 +6,7 @@
 - **Class** `LyraTranscriptFeed`, also available unregistered from `@aceshooting/lyra-ui/components/conversation/transcript-feed/transcript-feed.class.js`
 - **Family** `components/conversation/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 10 parts, 0 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---