@aceshooting/lyra-ui 6.1.0 → 6.2.0

package/llms/components/lr-table.md

@@ -6,6 +6,7 @@
 - **Class** `LyraTable`, also available unregistered from `@aceshooting/lyra-ui/components/data/table/table.class.js`
 - **Family** `components/data/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 34 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`
 
 ---
@@ -169,6 +170,9 @@ own "consumer computes/renders" contract rather than assuming addition.
   button's label once they've been revealed)
 - `showAllColumns: boolean = false` (attribute `show-all-columns`, reflected) — forces responsive
   priority columns visible and is updated by the built-in reveal button
+- `storageKey?: string` (attribute `storage-key`) — when set, persists `showAllColumns` to
+  `localStorage` (namespaced as `lr-table:${storageKey}`) and restores it on the next mount. Unset
+  (the default) touches storage not at all. Mirrors `lr-app-rail`'s identical `storage-key` pattern
 - `heatTintScale?: { min?: number; max?: number }` (attribute: false) — overrides the auto-derived
   heat-tint domain (min/max of every `heatValue` result across every currently-rendered row —
   post-sort, pre-pagination, the same rows `footer(rows)` already sees). Unset (the default) computes
@@ -237,6 +241,11 @@ element *or on any ancestor* and still reach the rule that reads it. It exists b
 forbids an attribute selector after `::part()` — `::part(row)[aria-selected='true']` is invalid CSS —
 so the only prior lever for restyling the selected row was overriding the library-wide
 `--lr-color-brand-quiet` token, which repaints everything else reading it.
+`--lr-table-header-sorted-bg` (default `transparent`) and `--lr-table-header-sorted-color` (default
+`inherit`) restyle the **currently-sorted** column's header cell (`[aria-sort]` other than `none`).
+Same shape and rationale as `--lr-table-row-selected-bg`: inline `var()` fallbacks, not on `:host`,
+because `::part(header-cell)[aria-sort]` is invalid CSS. The `sort-icon` part styles only the
+chevron; these tokens style the header cell itself.
 `--lr-table-sticky-offset` (default `0`) is measured and written inline per column by the component
 so multiple `sticky` columns stack instead of overlapping; it is a read-out, not a knob you set.
 `--lr-table-heat-t` is likewise component-written (each `[data-heat]` cell's position on the ramp).
@@ -262,11 +271,16 @@ so multiple `sticky` columns stack instead of overlapping; it is a read-out, not
 - only single-row selection is modeled (`selectedKey: string | number | null`);
   there's no bulk-select/checkbox-column API — you must hand-roll a checkbox column entirely inside
   a `cell()` callback if you need multi-select.
-- no `caption`/`aria-label` *property* exists, but a plain `aria-label` HTML attribute set on the
-  host **is** forwarded into the shadow-DOM `<table role="grid">` (read via
-  `this.getAttribute('aria-label')` at render time — a plain global-attribute read, not a reactive
-  Lit `@property`): `<lr-table aria-label="Scores">` gives the grid an accessible name; omit it and
-  the shadow table simply has none.
+- `accessibleLabel: string = ''` (attribute `accessible-label`) — a typed accessible name for the
+  `<table role="grid">`. A plain `aria-label` HTML attribute on the host is also forwarded (read via
+  `this.getAttribute('aria-label')` at render time) and serves as a fallback when `accessibleLabel`
+  is unset. Consumer-supplied text, so neither is run through `this.localize()`.
+- `caption: string = ''` — an optional visible `<caption>` (exposed as the `caption` CSS part). When
+  no `accessibleLabel`/host `aria-label` is present the caption also names the grid via
+  `aria-labelledby`.
+- A grid with **none** of `accessibleLabel`, host `aria-label`, or `caption` logs a one-time
+  `console.warn` on first render (dev signal) — an unnamed grid is an accessibility defect that
+  otherwise renders silently.
 - Full roving-tabindex grid keyboard pattern (one `tabindex="0"` stop among header cells, one among
   body rows) — Left/Right/Home/End move within the header row, Up/Down/Home/End move within the
   body, Down from the header enters the body's roving stop and Up from the body's first row returns

package/llms/components/lr-tabs.md

@@ -6,6 +6,7 @@
 - **Class** `LyraTabs`, also available unregistered from `@aceshooting/lyra-ui/components/layout/tabs/tabs.class.js`
 - **Family** `components/layout/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 5 parts, 4 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-tag.md

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

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

@@ -6,6 +6,7 @@
 - **Class** `LyraTaskList`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/task-list/task-list.class.js`
 - **Family** `components/agent-tools/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 11 parts, 4 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-terminal.md

@@ -6,6 +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
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---

package/llms/components/lr-test-results.md

@@ -6,6 +6,7 @@
 - **Class** `LyraTestResults`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/test-results/test-results.class.js`
 - **Family** `components/agent-tools/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 14 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-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

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, 4 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-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`
 
@@ -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,7 +99,7 @@ at another, since `placement` is a per-call option rather than a single global r
 
 ```html
 <script type="module">
-  import { toast } from '@aceshooting/lyra-ui';
+  import { toast } from '@aceshooting/lyra-ui/components/overlays/toast/toaster.js';
   document.getElementById('save-btn').addEventListener('click', () => toast('Saved!'));
 </script>
 ```

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`
 
@@ -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,7 +99,7 @@ at another, since `placement` is a per-call option rather than a single global r
 
 ```html
 <script type="module">
-  import { toast } from '@aceshooting/lyra-ui';
+  import { toast } from '@aceshooting/lyra-ui/components/overlays/toast/toaster.js';
   document.getElementById('save-btn').addEventListener('click', () => toast('Saved!'));
 </script>
 ```

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, 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`
 
 ---

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, 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-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, 4 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-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, 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-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`
 
 ---

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

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

package/llms/components/lr-tree.md

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

package/llms/components/lr-typing-indicator.md

@@ -6,6 +6,7 @@
 - **Class** `LyraTypingIndicator`, also available unregistered from `@aceshooting/lyra-ui/components/conversation/typing-indicator/typing-indicator.class.js`
 - **Family** `components/conversation/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 4 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`
 
 ---
@@ -39,10 +40,13 @@ variant), `cursor` (the blinking bar in the `cursor` variant)
 `size="sm"`), `--lr-typing-gap` (default `0.25rem`, `0.1875rem` at `size="sm"`),
 `--lr-typing-cursor-width` (default `0.125rem`, `0.09375rem` at `size="sm"`),
 `--lr-typing-cursor-height` (default `1em`, unaffected by `size`),
-`--lr-typing-dot-stagger-1` (default `600ms`, second dot), and
-`--lr-typing-dot-stagger-2` (default `1200ms`, third dot). Every variant uses the shared
-`--lr-transition-ambient` compound duration/timing token (default `1.8s ease-in-out`) as its
-animation cycle.
+`--lr-typing-dot-stagger-1` (default `600ms`, second dot), `--lr-typing-dot-stagger-2` (default
+`1200ms`, third dot), and `--lr-typing-duration` (default `var(--lr-transition-ambient)`, i.e.
+`1.8s ease-in-out`) — the compound duration/timing-function token every variant uses as its
+animation cycle. `--lr-typing-duration` is a dedicated alias: it defaults to the library-wide
+`--lr-transition-ambient` token (shared by every other ambient-looping component), but overriding
+it retimes only this component, leaving `--lr-transition-ambient` itself — and anything else keyed
+off it — untouched.
 
 **Optional peer deps:** none.
 
@@ -51,7 +55,7 @@ animation cycle.
 <lr-typing-indicator variant="pulse" size="sm"></lr-typing-indicator>
 <lr-typing-indicator variant="cursor"></lr-typing-indicator>
 <lr-typing-indicator
-  style="--lr-transition-ambient: 900ms ease-in-out; --lr-typing-dot-stagger-1: 300ms; --lr-typing-dot-stagger-2: 600ms"
+  style="--lr-typing-duration: 900ms ease-in-out; --lr-typing-dot-stagger-1: 300ms; --lr-typing-dot-stagger-2: 600ms"
 ></lr-typing-indicator>
 ```
 
@@ -70,9 +74,10 @@ decorative; `label` is the entire accessible content, nothing narrates individua
   state (`opacity: 1`, no transform, `animation: none !important`) rather than freezing on whatever
   frame the animation happened to be on — notably relevant for `cursor`, which would otherwise risk
   freezing on its invisible ("off") blink half.
-- `--lr-transition-ambient` is a compound `duration timing-function` value and cannot be divided
-  with `calc()`. When retiming it, override both stagger properties alongside it to preserve the
-  default one-third/two-thirds dot phasing, as shown above.
+- `--lr-typing-duration` (like the `--lr-transition-ambient` token it aliases by default) is a
+  compound `duration timing-function` value and cannot be divided with `calc()`. When retiming it,
+  override both stagger properties alongside it to preserve the default one-third/two-thirds dot
+  phasing, as shown above.
 - `size="sm"` shrinks the dot size, gap, and cursor width, but **not** `--lr-typing-cursor-height`
   (still `1em` at any size) — the cursor bar's height is meant to track surrounding text size via
   `1em`, not the component's own `size` property.

package/llms/components/lr-usage-badge.md

@@ -6,6 +6,7 @@
 - **Class** `LyraUsageBadge`, also available unregistered from `@aceshooting/lyra-ui/components/conversation/usage-badge/usage-badge.class.js`
 - **Family** `components/conversation/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 6 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-virtual-list.md

@@ -6,6 +6,7 @@
 - **Class** `LyraVirtualList`, also available unregistered from `@aceshooting/lyra-ui/components/layout/virtual-list/virtual-list.class.js`
 - **Family** `components/layout/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 5 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-voice-picker.md

@@ -6,6 +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
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---

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

@@ -6,6 +6,7 @@
 - **Class** `LyraWidgetRenderer`, also available unregistered from `@aceshooting/lyra-ui/components/conversation/widget-renderer/widget-renderer.class.js`
 - **Family** `components/conversation/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 4 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`
 
 ---