@aceshooting/lyra-ui 6.2.0 → 7.1.0

package/llms/components/lr-select.md

@@ -53,31 +53,29 @@ exactly like the multi-option case, until the trigger is actually activated.
   single-option auto-commit behavior described above
 - `value: string` — a getter/setter; always a single string (no `multiple` mode)
 
+**Methods:** `focus(options?)`, `blur()`, and `click()` forward to the internal trigger button.
+
 **Events:** `change` (native-style — selection changed), `input` (fired alongside `change` on every
 selection change — a native `<select>` doesn't meaningfully distinguish the two either), and
 `lr-change` (a prefixed compatibility alias fired after both, mirroring `<lr-checkbox>`'s
 `lr-change`). All three carry `detail: { value: string }` (the new selection) and fire only on a
-real change, never on a programmatic `value` write. Plus `lr-show`, `lr-hide`.
+real change, never on a programmatic `value` write. Plus `lr-show`, `lr-hide`, and bubbling,
+composed `focus`/`blur` events re-dispatched from the internal trigger.
 
 **Slots:** default (`<lr-option>` children), `label`, `hint`, `error` (overrides the `errorText`
-attribute when provided)
-
-**`lr-select` deliberately has no `start`/`end` adornment slots**, unlike
-`lr-input`/`lr-combobox`/`lr-date-input`. Two reasons, both structural rather than incidental:
-its `[part='trigger']` is a native `<button>`, and HTML's content model forbids interactive
-descendants inside one — so the slot could only ever accept decorative content, a materially
-different contract from the other three that would read as the same feature; and the trigger lays
-out with `justify-content: space-between`, so injecting a leading element pushes the selected label
-into the middle of the control instead of leaving it at the start. **Instead:** put a glyph in the
-`label` slot, or compose the select into `<lr-control-group>` alongside the adornment.
+attribute when provided), `start` (non-interactive adornment before the selected-value label), and
+`end` (non-interactive adornment after the label and before the expand icon). The adornments live
+inside the native trigger `<button>`, so never place links, buttons, inputs, or other interactive
+content in either slot.
 
 When hint/error content is present, the trigger's `aria-describedby` references stable shadow-local
 IDs for both messages (error first, then hint), so the visible supporting text is part of the
 control's accessible description.
 
-**CSS parts:** `form-control`, `form-control-label`, `trigger`, `listbox`, `group-label` (a heading
-row emitted inside the listbox whenever an option's `group` differs from the previous one's — a
-presentational `<div>`, not a `role="group"`; options with an empty `group` get no heading),
+**CSS parts:** `form-control`, `form-control-label`, `trigger`, `start`, `end`, `listbox`,
+`group-label` (a heading row emitted inside the listbox whenever an option's `group` differs from
+the previous one's — a presentational `<div>`, not a `role="group"`; options with an empty `group`
+get no heading),
 `option`, `option-dot` (the leading status dot, when a row's `dotColor` is set), `option-label`,
 `option-sub` (a row's secondary line, when `sub` is set), `expand-icon`, `error`, `hint`
 

package/llms/components/lr-selection-toolbar.md

@@ -0,0 +1,44 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/conversation.md — do not edit this file. -->
+
+# `lr-selection-toolbar`
+
+- **Import** `import '@aceshooting/lyra-ui/components/conversation/selection-toolbar/selection-toolbar.js';` (registers the tag; side-effect import)
+- **Class** `LyraSelectionToolbar`, also available unregistered from `@aceshooting/lyra-ui/components/conversation/selection-toolbar/selection-toolbar.class.js`
+- **Family** `components/conversation/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Themeable via** 6 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`
+
+---
+
+## `lr-selection-toolbar`
+
+Nonmodal, Escape-dismissible text-selection toolbar carrying selected text plus a format-neutral
+`DocumentLocator` into ask, quote, cite, and copy actions.
+
+**Properties:** `open: boolean = false` (reflected); `text: string = ''`;
+`anchor: DocumentLocator | null = null`, `rect: DOMRectReadOnly | null = null`, and
+`actions: SelectionAction[] = ['ask', 'quote', 'cite', 'copy']` (attribute: false);
+`label: string = ''`; `accessibleLabel: string | null = null` (attribute `aria-label`).
+`SelectionAction = 'ask' | 'quote' | 'cite' | 'copy'`.
+
+**Events:** `lr-selection-action` (`SelectionActionDetail = { action, text, anchor }`);
+`lr-dismiss` (Escape); `lr-copy-error` (`{ error }`). Copy uses the Clipboard API when available;
+the action event still reports the user intent if writing fails, alongside `lr-copy-error`.
+
+**CSS parts:** `toolbar`, `action`, `action-ask`, `action-quote`, `action-cite`, `action-copy`.
+
+**Themeable custom properties:** `--lr-selection-toolbar-inline-start` and
+`--lr-selection-toolbar-block-start` are normally computed from `rect`; hosts may override them to
+provide their own fixed-position anchor.
+
+**Slots:** none. **Optional peer deps:** none.
+
+```ts
+import '@aceshooting/lyra-ui/components/conversation/selection-toolbar/selection-toolbar.js';
+```
+
+**Additional API surface:**
+
+- `--lr-selection-toolbar-inline-shift` — Computed inline collision-avoidance offset.
+- `--lr-selection-toolbar-block-shift` — Computed block collision-avoidance offset.

package/llms/components/lr-slider.md

@@ -29,10 +29,13 @@ seamlessly right after. First-party invention (no Web Awesome equivalent).
 - `label: string = ''` — accessible name set as `aria-label` on the `role="slider"` thumb; a plain
   `aria-label` attribute on the host itself is honored as a fallback when this is left unset (matching
   `<lr-checkbox>`/`<lr-switch>`).
+- `valueFormatter?: SliderValueFormatter` (attribute: false) — maps the finite, clamped
+  `aria-valuenow` number to optional human-readable `aria-valuetext`. The formatter may return
+  `string | null | undefined`; a nullish result omits `aria-valuetext`. Leaving the property unset
+  preserves the existing numeric `aria-valuetext`.
 - `showValue: boolean = true` (attribute `show-value`) — whether to render the current numeric value as
   visible text next to the track. Not reflected; toggle it off via the `.showValue=${false}` property
-  binding — a bare `show-value="false"` content attribute is still truthy, since presence is all Lit's
-  default boolean converter checks.
+  binding or a plain `show-value="false"` content attribute.
 - Inherited from `FormAssociated`: `name: string = ''`, `value: string` (form-submitted string form),
   `disabled: boolean = false` (reflected), `required: boolean = false` (reflected).
 
@@ -68,6 +71,7 @@ when `show-value` is true)
   step="0.1"
   label="Temperature"
   .valueAsNumber=${0.7}
+  .valueFormatter=${(value) => `${value * 100}%`}
   @lr-input=${(e) => setDraftTemperature(e.detail.value)}
   @lr-change=${(e) => commitTemperature(e.detail.value)}
 ></lr-slider>
@@ -86,6 +90,9 @@ native range input either.
   value); ArrowUp/ArrowDown are never swapped, since direction only affects the horizontal inline axis.
 - Changing `min`/`max`/`step` after mount automatically re-clamps/re-snaps the current `value` in the
   next update — narrowing the domain can silently move the slider's value.
+- `valueFormatter` is presentation-only: `aria-valuenow`, the visible numeric readout, geometry,
+  form value, and emitted values stay numeric. With no formatter, `aria-valuetext` remains the
+  numeric string rendered by earlier versions; a nullish formatter result omits it.
 - A pointer drag fires `lr-input` continuously and a single `lr-change` on release; a keyboard step
   fires exactly one of each per press, but OS key-repeat while a key is held re-fires `lr-input` on
   every repeat while still only committing `lr-change` once, on the eventual keyup.

package/llms/components/lr-source-card.md

@@ -28,7 +28,7 @@ direct light-DOM children of the list (plain composition — no `.items` array p
 - `labelPlural: string = ''` (attribute `label-plural`) — fully consumer-built, already-pluralized
   header summary, e.g. `"3 sources"` or `"1 source"`; this component never counts or pluralizes on
   its own. Takes precedence over `label` when both are set. If neither is set, the header falls back
-  to the literal word `"Sources"`.
+  to the localized `sourceListDefaultLabel` string (English default: `"Sources"`).
 
 **Getters:** `sourceCount: number` — read-only, live-updated count of the currently-slotted children,
 handy for building a `label-plural` string reactively, e.g. `` list.labelPlural = `${list.sourceCount} sources` ``.
@@ -129,10 +129,9 @@ forwarding scenarios or engines that don't fire `slotchange` for content already
 time.
 
 **Known gotchas:**
-- This library has no built-in i18n/pluralization (the same stance `<lr-empty>`'s plain
-  `description` prop takes) — `lr-source-list`'s header text is entirely consumer-supplied via
-  `label`/`label-plural`; there's no automatic "N sources" string generation beyond the literal
-  `"Sources"` fallback.
+- `lr-source-list` does not automatically build an “N sources” plural summary: provide
+  `labelPlural` when that is wanted. Its no-label fallback is localized through
+  `sourceListDefaultLabel`, and a per-instance `.strings` override reaches the rendered header.
 - `lr-source-card`'s own expand/collapse (`full` slot, `lr-expand` event) is completely
   independent of the parent list's `expanded`/`lr-toggle` — collapsing the list doesn't reset an
   individual card's `fullExpanded` state, and there is no cross-talk between the two components at

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

@@ -28,7 +28,7 @@ direct light-DOM children of the list (plain composition — no `.items` array p
 - `labelPlural: string = ''` (attribute `label-plural`) — fully consumer-built, already-pluralized
   header summary, e.g. `"3 sources"` or `"1 source"`; this component never counts or pluralizes on
   its own. Takes precedence over `label` when both are set. If neither is set, the header falls back
-  to the literal word `"Sources"`.
+  to the localized `sourceListDefaultLabel` string (English default: `"Sources"`).
 
 **Getters:** `sourceCount: number` — read-only, live-updated count of the currently-slotted children,
 handy for building a `label-plural` string reactively, e.g. `` list.labelPlural = `${list.sourceCount} sources` ``.
@@ -129,10 +129,9 @@ forwarding scenarios or engines that don't fire `slotchange` for content already
 time.
 
 **Known gotchas:**
-- This library has no built-in i18n/pluralization (the same stance `<lr-empty>`'s plain
-  `description` prop takes) — `lr-source-list`'s header text is entirely consumer-supplied via
-  `label`/`label-plural`; there's no automatic "N sources" string generation beyond the literal
-  `"Sources"` fallback.
+- `lr-source-list` does not automatically build an “N sources” plural summary: provide
+  `labelPlural` when that is wanted. Its no-label fallback is localized through
+  `sourceListDefaultLabel`, and a per-instance `.strings` override reaches the rendered header.
 - `lr-source-card`'s own expand/collapse (`full` slot, `lr-expand` event) is completely
   independent of the parent list's `expanded`/`lr-toggle` — collapsing the list doesn't reset an
   individual card's `fullExpanded` state, and there is no cross-talk between the two components at

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

@@ -6,7 +6,7 @@
 - **Class** `LyraSourcePicker`, also available unregistered from `@aceshooting/lyra-ui/components/retrieval/source-picker/source-picker.class.js`
 - **Family** `components/retrieval/` — see `llms/index.md` for its siblings
 - **Optional peers** none
-- **Themeable via** 10 parts, 3 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 11 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`
 
 ---
@@ -38,9 +38,9 @@ fired after every toggle including select-all).
 
 **CSS parts:** `base`, `search` (the built-in filter `lr-input`, only when `searchable`),
 `select-all` (only when `showSelectAll`), `summary` ("{selected} of {total} selected"), `tree`
-(`role="tree"`), `item` (`role="treeitem"`), `checkbox` (tri-state glyph), `icon` (the
-`lr-file-icon` type badge), `label`, `empty` (`noData` when `sources` is empty, `noMatches` when a
-filter empties the tree).
+(`role="tree"`), `item` (`role="treeitem"`), `disclosure` (a folder row's expand/collapse button),
+`checkbox` (tri-state glyph), `icon` (the `lr-file-icon` type badge), `label`, `empty` (`noData`
+when `sources` is empty, `noMatches` when a filter empties the tree).
 
 **Themeable custom properties:** `--lr-source-picker-checked-bg` — the background of a fully-checked
 selection control: the `select-all` pill (whose resting default is `var(--lr-color-brand-quiet)`) and

package/llms/components/lr-split.md

@@ -21,8 +21,10 @@ auto-inserted between each adjacent pair.
   omitted/mismatched)
 - `defaultSizes: (number | string)[] = []` (attribute: false) — initialization-only fallback: a
   valid restored `storageKey` layout wins first; otherwise a valid `defaultSizes` wins over equal
-  distribution. Later reassignment never overwrites live drag/persisted state — set it once, at
-  mount. Each entry is either a plain **number** (percent-of-container, validated unchanged: a
+  distribution. Initialization occurs on the first update so framework property bindings committed
+  after connection in the same turn — including `defaultSizes` and `storageKey` — are honored
+  before the layout becomes live. Later reassignment never overwrites live drag/persisted state —
+  set it once, at mount. Each entry is either a plain **number** (percent-of-container, validated unchanged: a
   pure-number array that does not sum to ~100, e.g. `[30, 60]`, is still rejected and falls through
   to the equal split) or a CSS **length string** (`'200px'`, `'20%'`, `'3rem'`). When at least one
   entry is a length string, every entry is resolved against the measured container (numbers as

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

@@ -6,7 +6,7 @@
 - **Class** `LyraSpreadsheetViewer`, also available unregistered from `@aceshooting/lyra-ui/components/viewers/spreadsheet-viewer/spreadsheet-viewer.class.js`
 - **Family** `components/viewers/` — see `llms/index.md` for its siblings
 - **Optional peers** `xlsx` — see `llms/peers.md`
-- **Themeable via** 10 parts, 1 custom property — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 11 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`
 
 ---
@@ -37,9 +37,11 @@ Enter/Space. `lr-anchor-result` (`detail: { found }`) — fired after an `anchor
 `scrollToAnchor()` call. `lr-search-change` (`detail: { query, matchCount, activeIndex }`) — from
 `search()`/`searchNext()`/`searchPrevious()`/`clearSearch()`.
 
-**CSS parts:** `base`, `tabs`, `sheet`, `header-row`, `data-row`, `cell`, `cell-highlight` (a cell
-covered by a `highlights` entry), `rows`, `spinner`, and `error`. `data-row`, `cell` and
-`cell-highlight` are rendered inside the internal `<lr-virtual-list>` and forwarded via
+**CSS parts:** `base`, `tabs`, `sheet`, `header-row`, `data-row`, `cell`, `cell-highlight` (a
+structural cell covered by a `highlights` entry), `cell-highlight-action` (the native button
+filling a highlighted cell; focusable and emits `lr-highlight-activate`), `rows`, `spinner`, and
+`error`. `data-row`, `cell`, `cell-highlight`, and `cell-highlight-action` are rendered inside the
+internal `<lr-virtual-list>` and forwarded via
 `exportparts`, so `lr-spreadsheet-viewer::part(cell)` reaches them from a consumer stylesheet.
 
 **Themeable custom properties:** `--lr-spreadsheet-viewer-highlight-color` (default

package/llms/components/lr-stat.md

@@ -21,7 +21,8 @@ KPI/stat card — value + unit + label + optional icon/trend/caption.
 - `unit: string = ''`
 - `href?: string` — when it resolves to a safe URL, the root is a real whole-stat `<a>`; unsafe
   URL schemes keep the stat non-interactive
-- `target?: string` / `rel?: string` — forwarded to the anchor while `href` is active
+- `target?: string` — forwarded to the anchor while `href` is active; a nonempty target derives
+  `rel="noopener noreferrer"` rather than exposing a separately settable `rel`
 - `variant: 'neutral'|'success'|'warning'|'danger' = 'neutral'` (reflected)
 - `trend: number = NaN` (a `NaN` sentinel hides the trend pill entirely — set an actual number to
   show it)

package/llms/components/lr-stepper.md

@@ -6,7 +6,7 @@
 - **Class** `LyraStepper`, also available unregistered from `@aceshooting/lyra-ui/components/layout/stepper/stepper.class.js`
 - **Family** `components/layout/` — see `llms/index.md` for its siblings
 - **Optional peers** none
-- **Themeable via** 6 parts, 5 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 7 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`
 
 ---
@@ -16,9 +16,8 @@
 Ordered multi-step wizard/form navigation: an index/label per step, `current`/`completed`/`disabled`/
 `error` state, and click-to-jump. First-party invention (no Web Awesome equivalent). Fully
 data-driven and controlled, like `lr-table`'s `columns`/`rows` — it never mutates `steps` itself; a
-click, or Enter/Space on a non-disabled step, fires a cancelable `lr-step-select`, and the host
-decides whether/how `steps` changes in response (mirroring `lr-dialog-close`'s cancelable-event
-convention).
+click, or Enter/Space on a non-disabled step, fires a non-cancelable `lr-step-select`, and the host
+decides whether/how `steps` changes in response.
 
 **Properties:**
 - `steps: StepItem[] = []` (attribute: false) — `StepItem { id: string; label: string; state:
@@ -64,19 +63,20 @@ convention).
   doesn't resolve to a length. Also reflected as `data-effective-orientation` (only present while
   `orientationBreakpoint` resolves to a usable length).
 - `accessibleLabel: string | null = null` (attribute `aria-label`) — accessible name applied to the
-  `role="tablist"` step strip; attribute-reflects from a host-level `aria-label`. Unset, the
-  tablist renders without an `aria-label` (there is no localized default name).
+  `role="list"` step strip; attribute-reflects from a host-level `aria-label`. Unset, the list
+  renders without an `aria-label` (there is no localized default name).
 
 **Events:** `lr-step-select` (`detail: { index, id }`) — fired on click, or Enter/Space while
-focused, on a non-`disabled` step. Cancelable, though this component takes no default action of its
-own to prevent (it never mutates `steps`) — `preventDefault()` is available for a host that wants a
-single place to short-circuit its own listener's follow-up work. `lr-stepper-orientation-change`
+focused, on a non-`disabled` step. It is non-cancelable because the component takes no default
+action to veto: it never mutates `steps`. `lr-stepper-orientation-change`
 (`detail: { orientation }`) — fired only when an enabled `orientationBreakpoint` actually changes
 `effectiveOrientation`.
 
 **Slots:** none.
 
-**CSS parts:** `base` (root wrapper, `role="tablist"`), `step` (a single step button, `role="tab"`),
+**CSS parts:** `base` (root wrapper, `role="list"`), `step-item` (the `role="listitem"` wrapper for
+one step), `step` (a single native button; the current step carries `aria-current="step"` and every
+other step carries `aria-current="false"`),
 `step-icon` (optional leading topic glyph from the step's `icon` field; only rendered when the step
 has one, additionally to — never instead of — `step-index`/`step-check`), `step-index` (the numbered
 index chip, shown for `pending`/`current`/`error` steps), `step-check` (the completed-checkmark
@@ -127,9 +127,9 @@ each falls back to the token its rule used before. Otherwise shared tokens —
 - there's no built-in "step forward/back" method — advancing the wizard is entirely the host's job:
   react to `lr-step-select` (or its own Next/Back buttons) and reassign `steps` with updated
   `state` values.
-- `role="tablist"`/`role="tab"` back the keyboard/focus contract (roving tabindex, arrow-key
-  navigation) even though this isn't a `<lr-tabs>`-style panel switcher — there's no associated
-  `role="tabpanel"`, since this component renders no panel content of its own.
+- The stepper exposes ordered progress/navigation semantics (`list`/`listitem` plus native step
+  buttons), not tabs: it owns no tab panels. Roving tabindex and orientation-aware arrow-key
+  navigation remain available independently of those semantics.
 - Left/Right (horizontal) and Up/Down (vertical) are mutually exclusive per `orientation` — there's
   no single set of keys that works in both.
 

package/llms/components/lr-stream-status.md

@@ -63,10 +63,10 @@ visibility is driven purely by whether anything is slotted into it, not by `phas
 message text color, stalled border), `--lr-color-warning-quiet` (stalled background tint),
 `--lr-space-s` / `--lr-space-xs` (base gap, stalled padding, actions gap), `--lr-radius`
 (base corner radius), `--lr-transition-base` (background/border-color transitions and the
-streaming pulse animation's cycle length). The component also sets two internal, phase-driven
-custom properties (`--lr-stream-status-dot-color`, `--lr-stream-status-dot-opacity`) on
-`:host`, but its own `:host([phase="..."])` rules outrank a page-level override for every phase
-except the default `idle`, so these aren't a practical external theming hook.
+dot's color/opacity transitions), and `--lr-transition-ambient` (the streaming pulse cycle).
+The phase defaults flow through `--lr-stream-status-dot-color` and
+`--lr-stream-status-dot-opacity`; setting either custom property on the element or an ancestor
+wins through the shadow cascade and is the supported per-instance override.
 
 **Optional peer deps:** none.
 

package/llms/components/lr-streaming-text.md

@@ -48,7 +48,7 @@ of the stream arrives.
 cursor bar's inline size), `--lr-streaming-text-cursor-height` (default `1em`) — both
 component-specific, since no shared "inline cursor bar" token exists, the same pattern
 `<lr-typing-indicator>`'s own `--lr-typing-cursor-width`/`-height` use, plus shared
-`--lr-space-xs` (cursor's `margin-inline-start`) and `--lr-transition-base` (blink animation
+`--lr-space-xs` (cursor's `margin-inline-start`) and `--lr-transition-ambient` (blink animation
 cycle length).
 
 **Optional peer deps:** none — internally imports and auto-registers `<lr-markdown>` for

package/llms/components/lr-subagent-panel.md

@@ -0,0 +1,43 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/agent-tools.md — do not edit this file. -->
+
+# `lr-subagent-panel`
+
+- **Import** `import '@aceshooting/lyra-ui/components/agent-tools/subagent-panel/subagent-panel.js';` (registers the tag; side-effect import)
+- **Class** `LyraSubagentPanel`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/subagent-panel/subagent-panel.class.js`
+- **Family** `components/agent-tools/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Themeable via** 16 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`
+
+---
+
+## `lr-subagent-panel`
+
+Controlled nested-agent hierarchy with lifecycle badges, task/model context, guarded progress,
+selection, cancel, and retry intents. `SubagentRun.parentId` creates nesting; cycles and orphan
+parents remain renderable instead of recursing forever.
+
+**Properties:** `runs: SubagentRun[] = []` (attribute: false);
+`selectedRunId: string = ''` (attribute `selected-run-id`); `label: string = ''`.
+`SubagentRun = { id: string; parentId?: string; label: string; status: AgentStatusKind; task?:
+string; model?: string; progress?: number; startedAt?: number; endedAt?: number; metadata?:
+Record<string, unknown> }`.
+
+**Events:** `lr-run-select` (`{ run }`), `lr-cancel`/`lr-retry` (`{ runId }`).
+
+**CSS parts:** `base`, `list`, `run`, `run-selected`, `run-row`, `run-trigger`, `label`, `status`,
+`task`, `model`, `progress`, `actions`, `cancel`, `retry`, `limit`, `empty`.
+
+At most 500 runs render, and visual indentation is capped at 12 levels while ARIA hierarchy keeps
+the logical depth. Progress is finite and clamped. **Slots:** none. **Optional peer deps:** none.
+
+```ts
+import '@aceshooting/lyra-ui/components/agent-tools/subagent-panel/subagent-panel.js';
+```
+
+**Additional API surface:**
+
+- `part="limit"` — Resource-ceiling status shown when additional runs are omitted.
+- `--lr-subagent-panel-selected-border` — Selected run border. Default: `var(--lr-color-brand)`.
+- `--lr-subagent-panel-progress-track` — Progress track. Default: `var(--lr-color-border)`.
+- `--lr-subagent-panel-progress-fill` — Progress fill. Default: `var(--lr-color-brand)`.

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

@@ -6,7 +6,7 @@
 - **Class** `LyraSvgViewer`, also available unregistered from `@aceshooting/lyra-ui/components/viewers/svg-viewer/svg-viewer.class.js`
 - **Family** `components/viewers/` — see `llms/index.md` for its siblings
 - **Optional peers** `dompurify` — see `llms/peers.md`
-- **Themeable via** 13 parts, 2 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 16 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`
 
 ---
@@ -36,6 +36,9 @@ Enter/Space.
 
 **CSS parts:** `base`, `body`, `svg`, `spinner`, `error`, `highlight-layer` (wrapper around every
 rendered region highlight), `region-highlight` (one region highlight, `data-tone`, `data-active`),
+`region-highlight-target` (transparent activation geometry with an independent minimum hit area),
+`highlight-actions` (non-overlapping actions for multiple highlights), `region-highlight-action`
+(one action in that list),
 `frame-viewport`/`frame-content`/`frame-controls`/`frame-zoom-in`/`frame-zoom-out`/`frame-reset`
 (forwarded from the internal `<lr-zoomable-frame>` while `zoomable`).
 
@@ -48,7 +51,11 @@ inline `var()` fallback at the point of use rather than a `:host` declaration, s
 the element *or on any ancestor*: `::part(region-highlight)[data-active]` is invalid CSS — Shadow
 Parts forbids an attribute selector after `::part()` — so re-pointing a shared `--lr-color-*` token,
 and repainting everything else reading it, was previously the only way. Unset, it falls back to
-exactly the tokens the rule used before.
+exactly the tokens the rule used before. The tone-specific resting border and hover tint use
+`--lr-svg-viewer-highlight-accent-color`, `--lr-svg-viewer-highlight-success-color`,
+`--lr-svg-viewer-highlight-warning-color`, `--lr-svg-viewer-highlight-danger-color`, and
+`--lr-svg-viewer-highlight-neutral-color` (defaulting respectively to the matching
+brand/success/warning/danger/neutral color tokens).
 
 **Optional peer dependency:** `dompurify`.
 

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

@@ -6,7 +6,7 @@
 - **Class** `LyraSwatchPicker`, also available unregistered from `@aceshooting/lyra-ui/components/forms/swatch-picker/swatch-picker.class.js`
 - **Family** `components/forms/` — see `llms/index.md` for its siblings
 - **Optional peers** none
-- **Themeable via** 4 parts, 7 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 4 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`
 
 ---
@@ -48,7 +48,8 @@ swatch's interactive hit target, sized via `--lr-swatch-picker-hit-size` — def
 `[part='swatch'][aria-checked='true']`), `swatch-fill` (the filled circle inside it, sized via
 `--lr-swatch-picker-fill-size` — defaults to `--lr-size-1-5rem`, also swapped per `size` tier —
 rendered when the option has no `icon`), `swatch-icon` (the option's `icon` shape, rendered in its
-place when it has one). Exactly one of `swatch-fill`/`swatch-icon` is mounted per swatch, so the
+place when it has one, with its inherited `font-size` set to the same fill-size token so a `1em`
+glyph fills the wrapper). Exactly one of `swatch-fill`/`swatch-icon` is mounted per swatch, so the
 two never coexist.
 
 **Themeable custom properties:** `--lr-swatch-picker-selected-color` (ring color around the
@@ -84,12 +85,14 @@ and the per-tier `--lr-size-*` tokens.
 </script>
 ```
 
-For the shared gemstone accent mode, import the side-effect-free palette/glyph helper. The
-consumer still owns localized labels, display order, and the initial value:
+For the shared gemstone accent mode, import the Lit-free palette data entry. The glyph renderer
+remains available separately from `theme/gemstones.js` for Lit templates; palette-only consumers
+do not need to load Lit. The consumer still owns localized labels, display order, and the initial
+value:
 
 ```ts
 import '@aceshooting/lyra-ui/components/forms/swatch-picker/swatch-picker.js';
-import { GEMSTONES } from '@aceshooting/lyra-ui/theme/gemstones.js';
+import { GEMSTONES } from '@aceshooting/lyra-ui/theme/gemstones-data.js';
 
 const order = ['emerald', 'ruby', 'sapphire', 'hematite'] as const;
 picker.mode = 'gemstone';
@@ -117,4 +120,8 @@ picker.value = 'ruby';
 - the semantic `radiogroup` lives inside shadow DOM. Set `label` (preferred for reactive code) or a
   host `aria-label`; the component deliberately forwards the resulting name to that internal role.
 
+**Additional API surface:**
+
+- `--lr-swatch-picker-gap` — Gap between swatches. Default: `var(--lr-space-xs)`.
+
 ---

package/llms/components/lr-switch.md

@@ -34,7 +34,7 @@ control's visible, clickable label (same as `<lr-checkbox>`).
 **Events:** `lr-change` (`detail: { checked: boolean }`) — fired on a user toggle (click or
 Space/Enter); not fired for a programmatic `.checked` assignment.
 
-**Methods:** `focus(options?)` and `blur()` forward to the internal switch control.
+**Methods:** `focus(options?)`, `blur()`, and `click()` forward to the internal switch control.
 
 **Slots:**
 - default — label text, rendered next to the track. Clicking it toggles the switch, the same as

package/llms/components/lr-table.md

@@ -6,14 +6,17 @@
 - **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
+- **Themeable via** 34 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`
 
 ---
 
 ## `lr-table`
 
-Sort/select-aware data table. Sorting remains consumer-controlled; optional filtering, pagination,
+Sort/select-aware data table. Sorting is built in and client-side by default (`sortMode="client"`
+orders `rows` from `sortKey`/`sortDir` and the active column's `sortValue`); `sortMode="server"`
+renders `rows` in the order given for a server-ordered table, and `lr-sort` fires on header
+activation either way. Optional filtering, pagination,
 and loading chrome are built in while remaining controlled at the public API boundary. A
 `columns[].heatValue`-opted-in heat-tint mode paints a shared, normalized color-mix background across
 every tinted cell (auto-derived domain, or overridden via `heatTintScale`); `rowTotal`/`grandTotal`
@@ -23,8 +26,16 @@ own "consumer computes/renders" contract rather than assuming addition.
 
 **Properties:**
 - `columns: TableColumn<T>[] = []` (attribute: false) — `{ key, label, headerCell?, width?,
-  minWidth?, maxWidth?, resizable?, sortable?, align?: 'start'|'end', priority?: 'medium'|'low', sticky?: boolean |
+  minWidth?, maxWidth?, resizable?, sortable?, sortValue?, align?: 'start'|'end', priority?: 'medium'|'low', sticky?: boolean |
   'start' | 'end', footer?, cellStyle?, heatValue?, cell: (row) => unknown }` —
+  `sortValue(row) => string | number | null | undefined` supplies the comparable value backing
+  client-mode sorting for that column: a finite number sorts numerically, a string sorts through an
+  `Intl.Collator` built from the component's effective locale with `numeric: true` (so `item2`
+  precedes `item10`), and `null`/`undefined`/non-finite sorts **last in both directions** so
+  flipping `sortDir` never floats a block of blanks to the top. Omit it and the column sorts by its
+  stringified `cell()` output instead — meaningful only when `cell()` returns a string or number, so
+  define `sortValue` whenever `cell()` returns a template or element. Ignored under
+  `sortMode="server"` and on a column that is not `sortable`;
   `priority` progressively hides that column via a `@container` query as `[part='base']` narrows
   (`'low'` hides first, under a ~900px container width; `'medium'` next, under ~640px; both
   breakpoints are fixed in `table.styles.ts`, not themeable tokens), reversible via
@@ -97,6 +108,19 @@ own "consumer computes/renders" contract rather than assuming addition.
   the two consequences of the fixed algorithm worth knowing before opting in
 - `sortKey: string = ''` (attribute `sort-key`)
 - `sortDir: 'asc'|'desc' = 'asc'` (attribute `sort-dir`)
+- `sortMode: 'client'|'server' = 'client'` (attribute `sort-mode`, reflected) — mirrors
+  `paginationMode`'s identical split. `'client'` (the default) orders `rows` in the browser from
+  `sortKey`/`sortDir` and the active column's `sortValue`; `'server'` renders `rows` exactly as
+  given, for a table whose ordering already happened server-side. `lr-sort` is emitted on header
+  activation under both modes. With no `sortKey` set (the default) `'client'` is a **no-op** — the
+  input order is preserved verbatim — so a table that never sorts renders identically either way.
+  Sorting applies to the whole filtered set *before* client pagination slices the page, so page 1
+  holds the globally-smallest rows rather than a re-sorted slice
+- `defaultSortDir: 'asc'|'desc' = 'asc'` (attribute `default-sort-dir`) — the direction applied
+  whenever header activation switches sorting to a **different** column, including the first column
+  ever sorted. Re-activating the column that is already `sortKey` toggles between `'asc'` and
+  `'desc'` instead, so `defaultSortDir` never overrides a direction the user just chose for the
+  column they are still on. Set `'desc'` for a most-recent-first or highest-first table
 - `rowKey?: (row: T) => string | number` (attribute: false) — derives each row's stable identity for
   DOM-reconciliation and the delegated row click/keydown lookup; falls back to the row's array index
   when omitted, which is only safe while `rows` never reorders — set it whenever `rows` can be
@@ -143,7 +167,13 @@ own "consumer computes/renders" contract rather than assuming addition.
   mode slices rows; server mode renders the supplied page unchanged
 - Editable columns emit `lr-cell-edit` on commit and never mutate the supplied row object.
 - `groupBy?: (row: T) => string | number` (attribute: false) — inserts a non-focusable full-width
-  group row before each group
+  group row wherever this key changes between consecutive rendered rows. Supply `rows` with each
+  group already contiguous; the table renders the groups in their first-appearance order in `rows`
+  and never reorders them. A client-mode sort is applied **within** each group, so sorting a
+  grouped table on a column unrelated to the group key reorders rows inside their groups and
+  leaves the grouping intact. The one exception: when the sorted column's value is constant inside
+  every group — the group column itself, most obviously — there is nothing to reorder within a
+  group, so the **groups** are ordered by that value instead.
 - `groupLabel?: (key: string | number, rows: T[]) => unknown` (attribute: false) — custom group
   header content; without it, the group key is rendered as text
 - `expandedContent?: (row: T) => unknown` (attribute: false) — enables a leading expand toggle and
@@ -187,7 +217,8 @@ own "consumer computes/renders" contract rather than assuming addition.
   column × footer row). Only rendered when both `rowTotal` is set **and** at least one column defines
   `footer` — otherwise there is no footer row for it to occupy, and this renders nothing
 
-**Events:** `lr-sort` (`detail: { key }`, fired on sortable-header activation), `lr-row-click`
+**Events:** `lr-sort` (`detail: { key }`, fired on sortable-header activation — which also updates
+`sortKey`/`sortDir` itself, per `defaultSortDir` above), `lr-row-click`
 (`detail: { row }`), `lr-load-more` (fired on the "load more" button), `lr-columns-hidden-change`
 (`detail: { hidden: boolean }`, fired only on a real `columnsHidden` transition),
 `lr-columns-revealed` (`detail: { revealed: boolean }`), and `lr-row-expand-toggle`
@@ -241,6 +272,9 @@ element *or on any ancestor* and still reach the rule that reads it. It exists b
 forbids an attribute selector after `::part()` — `::part(row)[aria-selected='true']` is invalid CSS —
 so the only prior lever for restyling the selected row was overriding the library-wide
 `--lr-color-brand-quiet` token, which repaints everything else reading it.
+`--lr-table-row-stripe-bg` (default `transparent`) — the background of alternating body rows. The
+component marks the alternating rows itself, so this works without an invalid `::part(row)` attribute
+or structural-pseudo-class selector and does not affect group, expanded, hover, or selected rows.
 `--lr-table-header-sorted-bg` (default `transparent`) and `--lr-table-header-sorted-color` (default
 `inherit`) restyle the **currently-sorted** column's header cell (`[aria-sort]` other than `none`).
 Same shape and rationale as `--lr-table-row-selected-bg`: inline `var()` fallbacks, not on `:host`,
@@ -253,12 +287,13 @@ so multiple `sticky` columns stack instead of overlapping; it is a read-out, not
 **Optional peer deps:** none.
 
 ```html
-<lr-table id="t" sort-key="name" sort-dir="asc"></lr-table>
+<lr-table id="t" sort-key="name" sort-dir="asc" accessible-label="Items"></lr-table>
 <script type="module">
   const t = document.getElementById('t');
   t.columns = [
     { key: 'name', label: 'Name', sortable: true, cell: (r) => r.name },
-    { key: 'value', label: 'Value', align: 'end', cell: (r) => r.value },
+    // sortValue keeps the numeric column comparing as numbers, not as strings.
+    { key: 'value', label: 'Value', align: 'end', sortable: true, sortValue: (r) => r.value, cell: (r) => r.value },
   ];
   t.rows = [{ name: 'Alpha', value: 1 }, { name: 'Beta', value: 2 }];
   t.rowKey = (r) => r.name;
@@ -268,6 +303,23 @@ so multiple `sticky` columns stack instead of overlapping; it is a read-out, not
 ```
 
 **Known gotchas:**
+- activating a sortable header now writes `sortKey`/`sortDir` on the table itself, in **both** sort
+  modes — it is no longer a pure `lr-sort` notification. A `sortMode="server"` consumer that
+  re-sorts on `lr-sort` and pushes fresh `rows` back in is unaffected (the table renders whatever
+  order it is handed), but a consumer implementing a *tri-state* header (asc → desc → unsorted) must
+  drive `sortKey`/`sortDir` from its own `lr-sort` handler, since the built-in activation only
+  toggles between the two directions.
+- `sortValue`/`cell` are read off the column object by identity. Mutating a column **in place**
+  (`t.columns[0].sortValue = …`) neither re-renders nor re-sorts; assign a new `columns` array.
+- `groupBy` + client sorting are **not** in conflict: the sort runs per group, not across the whole
+  set, so group rows stay contiguous. The consequence is that the group order is normally yours to
+  control — it follows first appearance in `rows`. The single exception is a sort on a column whose
+  value is constant inside every group (the group column itself, a column functionally determined
+  by the group key, or any column at all when every group holds one row): the within-group sort
+  would be a provable no-op, so the groups are ordered by that constant value instead. That is what
+  keeps `aria-sort` and the header chevron honest — otherwise clicking the group column would flip
+  both while changing nothing. To force a group order in any other case, sort `rows` into it before
+  assigning them (or set `sort-mode="server"` and own the whole ordering).
 - only single-row selection is modeled (`selectedKey: string | number | null`);
   there's no bulk-select/checkbox-column API — you must hand-roll a checkbox column entirely inside
   a `cell()` callback if you need multi-select.
@@ -279,8 +331,8 @@ so multiple `sticky` columns stack instead of overlapping; it is a read-out, not
   no `accessibleLabel`/host `aria-label` is present the caption also names the grid via
   `aria-labelledby`.
 - A grid with **none** of `accessibleLabel`, host `aria-label`, or `caption` logs a one-time
-  `console.warn` on first render (dev signal) — an unnamed grid is an accessibility defect that
-  otherwise renders silently.
+  `console.warn` on first render in development builds only — an unnamed grid is an accessibility
+  defect that otherwise renders silently. Production and unknown/unbundled runtimes do not log it.
 - Full roving-tabindex grid keyboard pattern (one `tabindex="0"` stop among header cells, one among
   body rows) — Left/Right/Home/End move within the header row, Up/Down/Home/End move within the
   body, Down from the header enters the body's roving stop and Up from the body's first row returns