@aceshooting/lyra-ui 5.1.0 → 5.2.0

package/llms/components/lr-chat-message.md

@@ -89,6 +89,22 @@ between 4.x and 5.0.0, which silently turned one consumer's inner-surface scrim
 bubble (near-black text on `rgba(0,0,0,0.22)`, visible only by eye). These four are that stable
 contract.
 
+Two matching geometry properties cover the bubble's box:
+
+- `--lr-chat-message-bubble-padding` (default `var(--lr-space-m)`) — the bubble's padding.
+- `--lr-chat-message-bubble-radius` (default `var(--lr-radius)`) — the bubble's corner radius.
+  Bubble-only by design: `[part='collapse-button']` and `[part='retry-button']` keep reading the
+  shared `--lr-radius`, so a rounder bubble never desyncs those controls from the rest of the
+  library.
+
+**Use these instead of a `::part(bubble)` padding/radius override.** A `::part` declaration written
+in the consumer's tree outranks *every* rule inside this component's shadow tree, so a
+`::part(bubble) { padding: … }` rule silently suppresses the per-`status` treatments layered on the
+same element — `status="failed"`'s danger tint, `status="streaming"`'s border — along with the
+per-role fills above. The two properties are declared as `var()` fallbacks at the point of use and
+never on `:host`, both so they can't shadow an inherited value and so a container can set them once
+above a whole transcript rather than per message.
+
 Plus shared tokens `--lr-space-xs/-m`, `--lr-color-border`, `--lr-color-surface`,
 `--lr-color-brand-quiet`, `--lr-color-brand`, `--lr-color-text-quiet`, `--lr-color-danger`,
 `--lr-color-danger-quiet`, `--lr-radius`, `--lr-icon-button-size`, `--lr-focus-ring-*`,

package/llms/components/lr-chat-viewport.md

@@ -59,6 +59,18 @@ Renders no messages and computes no unread state itself — the host supplies `u
 virtualization of its own (`lr-virtual-list`); not a generic overflow surface (`lr-scroller`); no
 message semantics (`lr-chat-message`).
 
+**Sizing in virtual mode.** `[part='scroll']` steps aside and the slotted `lr-virtual-list`'s own
+viewport becomes the real scroller, so it is given this component's full height — otherwise it would
+scroll inside `lr-virtual-list`'s `24rem` default no matter how tall the viewport is. An explicit
+`block-size` on the slotted list is what makes that resolvable: without it the list host is
+auto-height, its own base percentage chains to `auto`, and the two size each other circularly.
+`<lr-thread-list>` solves the same problem by turning the internal list's shipped `24rem` into a
+flex-basis through `::part(base)`, which is not available here — that list lives in the *consumer's*
+light DOM, and `::slotted()` cannot be followed by `::part()`. Virtual mode therefore inherits this
+component's existing requirement of a height-bounded parent, exactly as slotted mode's own
+`[part='scroll']` already does. A document-tree declaration on the list (a consumer's own rule or an
+inline style) still wins over the built-in one.
+
 ```html
 <lr-chat-viewport unread-start-index="12" @lr-follow-change=${(e) => console.log(e.detail.following)}>
   <lr-chat-message role="user">…</lr-chat-message>

package/llms/components/lr-checkbox-group.md

@@ -19,3 +19,20 @@ selected value is submitted under `name` and `required` requires at least one se
 `accessibleLabel` (`aria-label`). **Slots:** default checkboxes, `label`, `hint`, `error`.
 **Events:** `input`, `change`, and `lr-change` with `{ value: string[] }`.
 **CSS parts:** `form-control`, `form-control-label`, `options`, `hint`, `error`.
+
+**`value` is a read-out of child state, not an input.** The children are the single source of
+truth. An internal sync recomputes `value` from them and reassigns it on every child toggle,
+`slotchange`, `name`/`required` change, blur, and `form.reset()` — so a host assignment is
+silently overwritten by the next of those. `connectedCallback()` runs that sync **before the first
+render**, which means even a constructor-time or template-time `.value=${…}` binding is discarded
+before anything can observe it. Assigning `value` logs a `console.warn` naming the property (once
+per group instance).
+
+- **To preselect**, set `checked` on the children: `<lr-checkbox value="a" checked>`.
+- **To read the selection**, use this property or the `lr-change` event detail.
+- **Give every child a distinct `value`.** `<lr-checkbox>`'s `value` defaults to `'on'`, so a group
+  of undifferentiated children submits several identical `FormData` entries and the submitted data
+  cannot say which one was checked. The group warns once per duplicated value when it sees this.
+- Making `value` authoritative is deliberately not implemented, for the same reason: a host
+  assigning `['on']` would check every child that kept the default. A distinct `defaultValue` API
+  could be added later without reversing any of the above.

package/llms/components/lr-checkbox.md

@@ -41,10 +41,37 @@ host so the control still has an accessible name.
 showing the checkmark/indeterminate dash), `checkmark` (the checkmark or indeterminate-dash glyph),
 `label` (wrapper around the default slot)
 
-**Themeable custom properties:** shared tokens only — `--lr-space-s`, `--lr-icon-button-size`,
+**Themeable custom properties:** `--lr-checkbox-label-indent` (below), plus shared tokens —
+`--lr-space-s`, `--lr-icon-button-size`,
 `--lr-color-border/-surface/-on-brand/-brand/-text/-danger`, `--lr-radius`,
 `--lr-transition-fast`, `--lr-focus-ring-width/-color/-offset`, `--lr-opacity-disabled`.
 
+**`--lr-checkbox-label-indent`** — the inline distance from the control's start edge to the start of
+the label text: the box's own floor plus the gap beside it. It defaults to
+`calc(min(var(--lr-icon-button-size), 1.75rem) + var(--lr-space-s))`, and the rendered gap is
+*derived* from it, so the advertised value and the real label offset cannot drift. Setting it on
+the element (or on `lr-checkbox` in your own stylesheet) moves the label.
+
+It is published so you can align your own per-option hint text under the label without re-deriving
+that formula by reading the shadow styles. **But custom properties inherit down, not sideways**, so
+a *sibling* node in your tree cannot read it off the checkbox. Align a sibling by computing the
+same formula from the `--lr-theme-*` inputs you control:
+
+```css
+.checkbox-hint {
+  padding-inline-start: calc(
+    min(var(--lr-theme-icon-button-size, 2.5rem), 1.75rem) + var(--lr-theme-space-s, 0.5rem)
+  );
+}
+```
+
+`--lr-checkbox-checked-bg` (default `var(--lr-color-brand)`) and `--lr-checkbox-checked-border`
+(default `var(--lr-color-brand)`) recolor `[part='box']`'s background/border while `checked` or
+`indeterminate` — a component-scoped indirection (the same pattern `lr-source-picker`'s own
+`--lr-source-picker-checked-bg`/`-border` pair uses) so a consumer can retint just this control's
+checked/indeterminate fill without hijacking the shared `--lr-color-brand` token everything else
+reads.
+
 **Optional peer deps:** none.
 
 ```html

package/llms/components/lr-chip-group.md

@@ -72,12 +72,30 @@ back to `--lr-chip-bg`), the density quintet `--lr-chip-font-size`, `--lr-chip-p
 `--lr-chip-padding-inline`, `--lr-chip-gap`, `--lr-chip-icon-size` (all five are rewritten by each
 `:host([size])` rule, so setting one directly on the element overrides that step of the scale; the
 `m` defaults are `--lr-font-size-sm` / `--lr-size-0-25rem` / `--lr-space-s` / `--lr-space-xs` /
-`--lr-font-size-sm`), plus shared tokens (`--lr-space-xs`, `--lr-space-s`,
+`--lr-font-size-sm`), the height pair `--lr-chip-min-height` / `--lr-chip-height` (below),
+plus shared tokens (`--lr-space-xs`, `--lr-space-s`,
 `--lr-color-brand`/`-brand-quiet`, `--lr-color-success`/`-success-quiet`,
 `--lr-color-warning`/`-warning-quiet`, `--lr-color-danger`/`-danger-quiet`,
 `--lr-icon-button-size`, `--lr-focus-ring-width`, `--lr-focus-ring-color`,
 `--lr-focus-ring-offset`, `--lr-transition-fast`).
 
+**Chip height — a floor and an exact cap:**
+
+- `--lr-chip-min-height` (default `--lr-size-1-5rem`) floors an **interactive** chip only — one in
+  toggle mode or with `removable` set. `2xs`/`xs`/`s`/`m` all share that `1.5rem` value because it
+  is the 24px WCAG 2.2 SC 2.5.8 target minimum and an interactive chip must never shrink below it;
+  `l` and `xl` raise it to their own taller floors. A passive display chip takes no floor from
+  this at all, and every default sits below the chip's own content-driven height, so the floor is
+  invisible until you raise it.
+- `--lr-chip-height` pins an **exact** height on `[part='base']` — interactive and passive chips
+  alike — so a row of chips can line up with a sibling control of a known height. It is
+  **undeclared by default**, which is what keeps the per-tier floor alive: `auto` is a valid
+  declared value that would win over the `var()` fallback arm and make `--lr-chip-min-height` dead
+  code, so never set it to `auto` — remove the declaration instead. Because the component never
+  declares it, it can be set inline, from an ancestor, or from an outer-tree rule.
+  **A value below 24px is for non-interactive display chips only**; pinning an interactive chip
+  that short breaks its tap target.
+
 **Optional peer deps:** none.
 
 ```html

package/llms/components/lr-chip.md

@@ -72,12 +72,30 @@ back to `--lr-chip-bg`), the density quintet `--lr-chip-font-size`, `--lr-chip-p
 `--lr-chip-padding-inline`, `--lr-chip-gap`, `--lr-chip-icon-size` (all five are rewritten by each
 `:host([size])` rule, so setting one directly on the element overrides that step of the scale; the
 `m` defaults are `--lr-font-size-sm` / `--lr-size-0-25rem` / `--lr-space-s` / `--lr-space-xs` /
-`--lr-font-size-sm`), plus shared tokens (`--lr-space-xs`, `--lr-space-s`,
+`--lr-font-size-sm`), the height pair `--lr-chip-min-height` / `--lr-chip-height` (below),
+plus shared tokens (`--lr-space-xs`, `--lr-space-s`,
 `--lr-color-brand`/`-brand-quiet`, `--lr-color-success`/`-success-quiet`,
 `--lr-color-warning`/`-warning-quiet`, `--lr-color-danger`/`-danger-quiet`,
 `--lr-icon-button-size`, `--lr-focus-ring-width`, `--lr-focus-ring-color`,
 `--lr-focus-ring-offset`, `--lr-transition-fast`).
 
+**Chip height — a floor and an exact cap:**
+
+- `--lr-chip-min-height` (default `--lr-size-1-5rem`) floors an **interactive** chip only — one in
+  toggle mode or with `removable` set. `2xs`/`xs`/`s`/`m` all share that `1.5rem` value because it
+  is the 24px WCAG 2.2 SC 2.5.8 target minimum and an interactive chip must never shrink below it;
+  `l` and `xl` raise it to their own taller floors. A passive display chip takes no floor from
+  this at all, and every default sits below the chip's own content-driven height, so the floor is
+  invisible until you raise it.
+- `--lr-chip-height` pins an **exact** height on `[part='base']` — interactive and passive chips
+  alike — so a row of chips can line up with a sibling control of a known height. It is
+  **undeclared by default**, which is what keeps the per-tier floor alive: `auto` is a valid
+  declared value that would win over the `var()` fallback arm and make `--lr-chip-min-height` dead
+  code, so never set it to `auto` — remove the declaration instead. Because the component never
+  declares it, it can be set inline, from an ancestor, or from an outer-tree rule.
+  **A value below 24px is for non-interactive display chips only**; pinning an interactive chip
+  that short breaks its tap target.
+
 **Optional peer deps:** none.
 
 ```html

package/llms/components/lr-chunk-inspector.md

@@ -37,13 +37,41 @@ activated).
 
 **Slots:** none.
 
-**CSS parts:** `base` (`role="group"`), `chunk` (`role="listitem"`), `score` (visible percent text),
-`score-bar` (`aria-hidden` track), `score-fill` (tone-mapped fill), `open-button`, `title` (the
-`<span>` inside `open-button` carrying the visible title text), `text` (line-clamped unless
-expanded, omitted when `compact`), `toggle` ("Show more"/"Show less", omitted when `compact`),
+**CSS parts:** `base` (`role="group"`), `chunk` (one chunk row; carries `role="listitem"` only
+below `virtualize-at` — while virtualized the surrounding `lr-virtual-list` row supplies that role
+instead), `chunk-current` (additional part on the row matching `activeId`), `score` (visible
+percent text), `score-current` (additional part on the current row's score line), `score-bar`
+(`aria-hidden` track), `score-fill` (tone-mapped fill), `score-fill-success` /
+`score-fill-warning` / `score-fill-danger` (additional part on the fill, one per scoring tier),
+`open-button`, `title` (the `<span>` inside `open-button` carrying the visible title text), `text`
+(omitted when `compact`), `text-clamped` (additional part on a `text` preview that is still
+collapsed; dropped once expanded), `toggle` ("Show more"/"Show less", omitted when `compact`),
 `empty` (shown when `chunks` is empty).
 
-**Themeable custom properties:** shared tokens only.
+Every row-level part is reachable through `::part()` in both rendering paths: above
+`virtualize-at` the row lives in the internal `lr-virtual-list`'s shadow root and its parts are
+re-exported from there under the same names. Row *state* is exposed as an additional part name
+rather than as an attribute on the part, because Shadow Parts forbids an attribute selector after
+`::part()` — `::part(chunk)[aria-current='true']` is invalid CSS. The equivalent attributes
+(`aria-current`, `data-tone`, `data-clamped`) are still present on the elements. A state part is a
+second token in the same `part` attribute, so a `[part~="…"]` (not `[part="…"]`) selector is the
+one that matches inside a tree.
+
+**Themeable custom properties:** `--lr-chunk-inspector-current-bg` (default
+`var(--lr-color-brand-quiet)`) — the background of the chunk matching `activeId`.
+`--lr-chunk-inspector-current-color` (default `var(--lr-color-text)`) — the text color of that
+chunk's `score` line (`::part(score-current)`). Both are inline `var()` fallbacks at the point of
+use rather than `:host` declarations, so either can be set on the element *or on any ancestor*:
+`::part(chunk)[data-active]` is invalid CSS — Shadow Parts forbids an attribute selector after
+`::part()` — which is why the current-chunk state is also published as its own part name
+(`chunk-current`, `score-current`); either the custom properties or `::part(chunk-current)` will
+retint it.
+
+**They are a contrast-sensitive pair — override them together, never one alone.** The `-current-color`
+hook exists precisely because the quiet token it replaces only reaches about 4.24:1 against the
+current background; keep any override at 4.5:1 or better against `--lr-chunk-inspector-current-bg`.
+
+Plus shared tokens otherwise.
 
 **Optional peer deps:** none.
 

package/llms/components/lr-code-block-core.md

@@ -83,7 +83,12 @@ body ended; `anchor` is a `line-range` anchor covering the selected lines).
 `code`, `line-highlight`, `line-button` — identical set to `<lr-code-block>`.
 
 **Themeable custom properties:** identical to `<lr-code-block>` — `--lr-code-block-max-height`,
-`--lr-code-block-font`, plus the same shared tokens.
+`--lr-code-block-font`, `--lr-code-block-tab-size` (default `2`, applied to `[part='pre']`),
+`--lr-code-block-active-line-outline-color` (default `var(--lr-color-brand)`), plus the same shared
+tokens. Both of the last two are inline `var()` fallbacks at the point of use rather than `:host`
+declarations, so a page-, container-, or theme-level value reaches them; see `<lr-code-block>` above
+for the full rationale, including why `<lr-markdown>`/`<lr-markdown-core>` must declare the tab-size
+fallback separately.
 
 **Optional peer deps:** `shiki` (specifically its `shiki/core`, `shiki/engine/oniguruma`,
 `shiki/wasm`, and `shiki/themes/github-{light,dark}.mjs` subpaths — never `shiki`'s main entry point,

package/llms/components/lr-code-block.md

@@ -89,11 +89,30 @@ are both set)
 **Themeable custom properties:** `--lr-code-block-max-height` (default `none` — the consumer-tunable
 scroll cap; only takes effect once `max-height` is set), `--lr-code-block-font` (default
 `ui-monospace, SFMono-Regular, Menlo, Consolas, monospace` — no shared `--lr-*` monospace
-token exists to resolve through), plus shared tokens `--lr-color-border`, `--lr-radius`,
+token exists to resolve through), `--lr-code-block-tab-size` (default `2` — tab width for the
+rendered code, applied to `[part='pre']`), `--lr-code-block-active-line-outline-color` (default
+`var(--lr-color-brand)` — the outline around the line marked active by `active-highlight-id`), plus shared tokens `--lr-color-border`, `--lr-radius`,
 `--lr-color-surface`, `--lr-space-xs/-s/-m`, `--lr-font`, `--lr-color-text-quiet`,
 `--lr-color-text`, `--lr-color-brand`/`-brand-quiet`, `--lr-transition-fast`,
 `--lr-focus-ring-width/-color/-offset`.
 
+`--lr-code-block-tab-size` carries the same default as `--lr-code-editor-tab-size`, so the editable
+and read-only code surfaces agree on what a literal tab looks like. It is declared as a `var()`
+fallback **at the point of use, not on `:host`** — a `:host` rule is re-stamped on every instance and
+shadows any inherited value, so a page- or container-level declaration could never reach it. It is
+also never written as an inline `tab-size`: `shiki` puts its own `style` attribute on the highlighted
+`<pre>`, and an inline declaration is the one thing a host override cannot beat. `<lr-markdown>` and
+`<lr-markdown-core>` carry the same fallback for their own `code-block` part because they are
+**sibling** custom elements rather than descendants of this one — no single declaration covers both.
+The identical value can still look different across the two: this component is `white-space: pre`
+while a markdown code block inherits `pre-wrap`, and tab stops restart at each visual line, so a
+wrapped line's tabs diverge.
+
+`--lr-code-block-active-line-outline-color` retints just the active line's outline and leaves every
+other `--lr-color-brand` surface in the component — the header language pill, hover states, the focus
+ring — alone. It too is an inline `var()` fallback rather than a `:host` declaration, deliberately,
+so it inherits: set it on the element, on an ancestor, or at the theme level.
+
 **Optional peer deps:** `shiki` (lazy-loaded and cached once per page by `code-loader.ts`'s
 `loadShikiHighlighter()`, which builds a single `Highlighter` seeded with the bundled `github-light`/
 `github-dark` "dual themes" and *zero* language grammars up front; each `language` a

package/llms/components/lr-combobox.md

@@ -35,7 +35,9 @@ shared `FormAssociated` mixin — see gotchas).
 - `errorText: string = ''` (attribute `error-text` — static error copy shown below the hint;
   overridden by slotted `error` content when provided)
 - `open: boolean = false` (reflected)
-- `clearable: boolean = false` (reflected) — displays the clear button while a value is selected
+- `clearable: boolean = false` (reflected) — displays the clear button while there is something to
+  clear on **either** axis this control owns: a committed selection, or *visible* filter text. See
+  "the clear button covers two axes" below
 - `withClear: boolean = false` (attribute `with-clear`) — deprecated compatibility alias for
   `clearable`; either property enables the same clear button
 - `autocomplete: string = 'off'`, `inputMode: string = ''` (attribute `inputmode`),
@@ -96,10 +98,31 @@ the filter silently, mirroring how `<lr-input>`'s `lr-input` only reports user e
 `lr-show` and `lr-hide` report listbox visibility transitions.
 The internal input's `focus` and `blur` are re-dispatched as bubbling, composed host events.
 
-**Slots:** default (`<lr-option>` children), `label`, `hint`, `error` (overrides the `errorText`
-attribute when provided)
+**The clear button covers two axes, and announces only the one that moved.** A combobox owns both a
+committed selection and an in-progress filter query, so the button renders whenever either has
+something to clear, and one press clears both:
+
+- Clearing a selection emits `input`, then `change`, then `lr-clear` — and, if the query was also
+  non-empty, `lr-filter` with an empty `value`.
+- A **query-only** clear (nothing selected, just typed text) emits `lr-filter` with an empty
+  `value` and deliberately **no** `change` and **no** `lr-clear`. There was no selection
+  transition to report, so announcing one would be a lie. Don't listen for `lr-clear` to detect
+  "the user emptied the field" — listen for `lr-filter` when you care about the query.
+- The query half of the render gate is scoped to states where the query is actually *visible*: an
+  open listbox in single-select, or any time in `multiple` mode. A closed single-select shows the
+  selected label rather than the query, so a stale query alone never surfaces a button offering to
+  clear text the user cannot see.
 
-**CSS parts:** `form-control`, `form-control-label`, `combobox`, `tags`, `tag`,
+**Slots:** default (`<lr-option>` children), `label`, `hint`, `error` (overrides the `errorText`
+attribute when provided), plus two adornment slots:
+- `start` — content at the inline-start of the trigger row, before the selected-value tags and the
+  filter input. It is decorative chrome, **not** an option: only `<lr-option>` elements in the
+  default slot are ever collected into the option list.
+- `end` — content after the filter input and the built-in clear action, and before the expand icon,
+  so consumer content never sits outboard of the dropdown chevron.
+
+**CSS parts:** `form-control`, `form-control-label`, `combobox`, `start` and `end` (the two
+adornment-slot wrappers, each `hidden` while nothing is slotted into it), `tags`, `tag`,
 `tag__remove-button`, `combobox-input`, `clear-button`, `expand-icon`, `listbox`, `option`,
 `option-dot` (the leading status dot, when a row's `dotColor` is set), `option-icon` (the decorative
 leading visual for an async row), `option-label`, `option-sub` (a row's secondary line, when `sub`
@@ -111,6 +134,18 @@ indicator from `maxRender`), `error`, `hint`
 `--lr-combobox-tag-font-size`, and `--lr-combobox-expand-size` (the decorative icon box; each
 standard size supplies an aligned default), plus shared tokens.
 
+`--lr-combobox-option-active-bg` (default `var(--lr-color-brand-quiet)`) recolors the background of
+a hovered or keyboard-active `[part='option']` row — the same per-component indirection
+`lr-select`'s identical `--lr-select-option-active-bg` uses, so a consumer can retheme just this
+row state without hijacking the shared `--lr-color-brand-quiet` token library-wide.
+
+`--lr-combobox-trigger-height` pins an **exact** input-container height (both floors and caps it),
+for pixel-matching an `<lr-input>` or `<lr-select>` in the same toolbar row. It is **undeclared by
+default**, leaving `--lr-combobox-trigger-min-height` as a floor only and the row free to grow —
+see "exact-height hatches" under `lr-input` for why `auto` is not a way to opt back out. Intended
+for a single-row combobox: in `multiple` mode, a tag row long enough to wrap overflows the pinned
+box visibly (nothing is clipped or made unreachable), so leave it unset there.
+
 **Optional peer deps:** none.
 
 ### `lr-option`

package/llms/components/lr-command-palette.md

@@ -19,10 +19,13 @@ dismissal, ref-counted document scroll lock).
 **Properties:**
 - `open: boolean = false` (reflected)
 - `commands: LyraCommand[] = []` (attribute: false) — `{ id, label, description?, group?, shortcut?,
-  keywords?, disabled?, onSelect? }`. Filtering is case-insensitive substring matching over
-  `label` + `description` + `group` + `keywords` joined together (not fuzzy/subsequence), memoized
-  per `commands` array identity — reassign the array, never mutate it in place. Consecutive commands
-  sharing a `group` render one `[part='group']` heading, so pre-sort by group yourself.
+  keywords?, disabled?, icon?, onSelect? }`. `icon` is an optional leading glyph (a `TemplateResult`,
+  an emoji string, etc. — not restricted to a square icon) rendered in the `icon` part before the
+  label; a command with no `icon` renders no `icon` part at all. Filtering is case-insensitive
+  substring matching over `label` + `description` + `group` + `keywords` joined together (not
+  fuzzy/subsequence), memoized per `commands` array identity — reassign the array, never mutate it
+  in place. Consecutive commands sharing a `group` render one `[part='group']` heading, so pre-sort
+  by group yourself.
 - `shortcut: string = 'mod+k'` — global toggle chord parsed as `+`-separated parts; `mod` resolves to
   Cmd on Mac and Ctrl elsewhere. The listener is on `window`, added in `connectedCallback`.
 - `accessibleLabel: string = ''` (attribute `aria-label`) — overrides the localized dialog name
@@ -41,10 +44,18 @@ fired before the command's own `onSelect` runs and before the palette closes).
 
 **CSS parts:** `backdrop`, `dialog` (the `role="dialog" aria-modal="true"` panel), `search` (the
 input row), `input` (the `type="search"` field), `list` (the `role="listbox"`), `group` (a group
-heading), `command` (a `role="option"` button), `description`, `shortcut`, `empty`.
+heading), `command` (a `role="option"` button), `icon` (a command's leading icon glyph; only
+rendered when the command has one), `description`, `shortcut`, `empty`.
 
 **Themeable custom properties:** `--lr-command-palette-z-index` (default
 `var(--lr-overlay-stack-index, var(--lr-layer-modal))`), `--lr-command-palette-offset-block-start`
 (default `12vh` — how far down the viewport the dialog sits), `--lr-command-palette-max-inline-size`
-(default `var(--lr-size-48rem)`), `--lr-command-palette-max-block-size` (default `70vh`), and
-`--lr-command-palette-list-max-block-size` (default `50vh` — the scrolling result list).
+(default `var(--lr-size-48rem)`), `--lr-command-palette-max-block-size` (default `70vh`),
+`--lr-command-palette-list-max-block-size` (default `50vh` — the scrolling result list), and
+`--lr-command-palette-active-bg` (default `var(--lr-color-brand-quiet)` — the background of the
+active, keyboard-highlighted command row). That last one is an inline `var()` fallback at the point
+of use rather than a `:host` declaration, so it can be set on the element *or on any ancestor*:
+`::part(command)[data-active='true']` is invalid CSS (Shadow Parts forbids an attribute selector
+after `::part()`), so highlighting the active row previously required hijacking the library-wide
+`--lr-color-brand-quiet` token and repainting everything else that read it. Unset, it falls back to
+that token, so rendering is unchanged.

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

@@ -22,6 +22,13 @@ number` (attribute: false, epoch milliseconds), `files: CommitFileChange[] = []`
 'conflicted' | 'ignored'` (shared with `lr-file-tree`); the diffstat is summed from `additions`/
 `deletions` across `files`. `filesCollapsed:
 boolean = true` (attribute `files-collapsed`, reflected), and `copyable: boolean = true` (reflected).
+`compact: boolean = false` (reflected) — tighter `[part="base"]` padding for a commit rendered as a
+row in a list or PR timeline, same convention as `<lr-agent-run>`'s own `compact`; the border stays,
+so pair it with `appearance="plain"` to drop the chrome entirely. `appearance: 'card' | 'plain' =
+'card'` (reflected) — mirrors `lr-card`'s/`<lr-agent-run>`'s `appearance` vocabulary: `'card'` keeps
+the bordered, padded box, `'plain'` removes the border, padding, and corner radius so a commit nested
+in a host list that already draws its own row chrome doesn't double it; `plain` wins over `compact`
+when both are set.
 
 **Slots:** `actions` — trailing header controls (e.g. an "open PR" button).
 
@@ -31,3 +38,6 @@ boolean = true` (attribute `files-collapsed`, reflected), and `copyable: boolean
 **CSS parts:** `base`, `subject`, `body`, `hash`, `meta`, `author`, `time`, `diffstat`, `additions`,
 `deletions`, `files-toggle`, `file` (carries `data-status`), `file-path`, `file-additions`,
 `file-deletions`, `copy-button`, and `actions`.
+
+**Themeable custom properties:** `--lr-commit-card-compact-padding` (default `var(--lr-space-s)`) —
+`[part="base"]` padding while `compact`.

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

@@ -24,6 +24,11 @@ graph or membership fetching — `lr-drill` asks the host to load members/subgra
 - `maxMembers: number = 8` (attribute `max-members`) — remaining members collapse into a "+N"
   overflow chip
 - `compact: boolean = false` (reflected) — omits the summary excerpt and member chips
+- `appearance: 'card' | 'plain' = 'card'` (reflected) — visual chrome, mirroring `lr-card`'s
+  `appearance` vocabulary and this component's sibling `lr-entity-card`'s identical property.
+  `'card'` (the default) keeps the bordered, filled, padded box; `'plain'` removes the border,
+  background, and padding, so a card nested inside a container that already draws a border doesn't
+  double the frame.
 
 **Events:** `lr-drill` (`detail: { id }`, the drill button, header, or overflow chip — all three
 mean "show me this whole community"), `lr-entity-activate` (`detail: { id }`, a member chip was

package/llms/components/lr-confirm-bar.md

@@ -27,7 +27,14 @@ free-form heading override for non-tool proposals; wins over `toolName`. `args:
 (attribute: false) — shown read-only inside a collapsed `lr-details` + `lr-json-viewer` when
 defined. `decision: 'approved' | 'denied' | null = null` (reflected) — decided state, set by the
 component on activation and host-writable (an externally-resolved decision renders identically but
-emits nothing). `tone: 'neutral' | 'danger' = 'neutral'` (reflected).
+emits nothing). `tone: 'neutral' | 'danger' = 'neutral'` (reflected). `compact: boolean = false`
+(reflected) — collapses the bar from a full card (bordered, padded, `display: block` surface) to a
+single inline row with no chrome of its own, for a confirmation that has to live inside an existing
+container: a table cell, a card's action row, a toolbar. The host becomes `inline-flex`, and the
+narrow-allocation `@container` treatment is switched off — a compact bar is *expected* to be narrow,
+so stretching the buttons to fill would be exactly wrong. Re-chrome it through the
+`--lr-confirm-bar-compact-*` properties below. Everything else is unchanged: the event shapes, the
+focus-to-`[part="status"]`-before-unmount contract, and `role="group"` with its heading label.
 
 **Slots:** default — supplementary body content between the heading and the actions (e.g. a
 `lr-diff-view`). `footer` — extra content at the start of the action row.
@@ -40,6 +47,24 @@ details/json-viewer wrapper, only rendered when `args` is defined), `footer`, `d
 `approve-button` (named identically to the dialog's parts), `status` (the decided-state text, always
 present in the DOM as a focus landing spot).
 
+**Themeable custom properties:** the `compact` presentation is deliberately chrome-less by default
+and re-chromed entirely through five properties, all scoped to `[part="base"]` while `compact`:
+`--lr-confirm-bar-compact-padding` (default `0`, any padding shorthand),
+`--lr-confirm-bar-compact-gap` (default `var(--lr-space-s)`, the gap between the row's items),
+`--lr-confirm-bar-compact-border` (default `none`, any `border` shorthand),
+`--lr-confirm-bar-compact-background` (default `transparent`) and
+`--lr-confirm-bar-compact-radius` (default `0` — only visible once the border or background is set).
+They are inline `var()` fallbacks at their point of use rather than `:host` declarations, so any of
+them can be set on the element *or on any ancestor*, which is what makes "give every compact confirm
+bar in this panel a hairline border" a one-rule change on the panel.
+
+**Known gotchas:**
+- `[part="status"]` is always rendered and must never be given `display: none`. Deciding moves focus
+  to it synchronously, before the Deny/Approve buttons unmount, so hiding it would drop focus to
+  `<body>`. The shipped `:empty` rule on it has never matched, and that is load-bearing.
+- `[part="deny-button"]` and `[part="approve-button"]` are raw `<button>` elements, not composed
+  `lr-button`s, so `--lr-button-*` theming does not reach them. Style them through their parts.
+
 ```html
 <lr-tool-call-chip status="pending"></lr-tool-call-chip>
 <lr-confirm-bar tool-name="run_shell" .args=${args}

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

@@ -32,6 +32,15 @@ First-party invention (no Web Awesome equivalent).
   rename button never renders and the row can never enter its editing state; flipping it to `false`
   while a rename is already in progress cancels that edit (discards the draft, like Escape) rather
   than leaving it stranded and still committable.
+- `compact: boolean = false` (reflected) — tighter row padding and gaps, for the dense history
+  sidebars these rows usually render in (same convention as `lr-empty`'s `compact`). Tightens
+  `[part='base']`'s padding to `var(--lr-space-xs) var(--lr-space-s)` and its gap to
+  `var(--lr-space-2xs)`, and collapses `[part='content']`'s inter-line gap to `0`. Deliberately
+  changes nothing else: it does **not** shrink `[part='rename-button']` below the shared
+  `--lr-icon-button-size` target floor, hide the excerpt, or reduce the excerpt/timestamp font
+  sizes — so a row carrying a rename button or slotted `actions` still floors at roughly that icon
+  size plus the compact padding, while a row with `editable=false` and no actions collapses much
+  further.
 - `spellcheck: boolean = true` — forwarded to the in-place rename `<input>`; `spellcheck="false"` is
   parsed as false (not Lit's default boolean-attribute behavior)
 - `autocapitalize: string = ''` — forwarded to the in-place rename `<input>`; empty omits the attribute
@@ -67,7 +76,33 @@ in-place rename `<input>`'s own `focus`, for the same reason as `blur`)
 **CSS parts:** `base`, `option`, `content`, `title`, `title-input`, `rename-button`, `excerpt`,
 `timestamp`, `actions`
 
-**Themeable custom properties:** shared tokens only — `--lr-space-xs/-s/-m`, `--lr-radius`,
+**Themeable custom properties:** `--lr-conversation-item-active-bg` (default
+`var(--lr-color-brand-quiet)`) — the row's background while `active`. `--lr-conversation-item-active-color`
+(default `var(--lr-color-text)`) — the text color of `[part='excerpt']` and `[part='timestamp']`
+while `active`. Both are declared as inline `var()` fallbacks at the point of use and never on
+`:host`, so either can be set on the element *or on any ancestor* (a thread-list wrapper, a page
+theme layer); `::part(base)[active]` is not valid CSS — Shadow Parts forbids an attribute selector
+after `::part()` — so the only previous lever was overriding the library-wide `--lr-color-brand-quiet`
+token and repainting everything else reading it. Unset, each falls back to exactly the token its rule
+used before.
+
+**These two are a contrast-sensitive pair — override them together, never one alone.** The
+`-active-color` hook exists precisely because the quiet text tone only reaches about 4.25:1 against
+the default active background; keep any override at 4.5:1 or better against it. And note that
+`[part='title']` is *not* restyled by the pair — it keeps `--lr-color-text` regardless — so a dark
+custom active background needs its own title color set alongside them, or the title drops below
+contrast while the excerpt stays legible.
+
+`--lr-conversation-item-compact-padding` (default `var(--lr-space-xs) var(--lr-space-s)`) —
+`[part='base']`'s padding while `compact`. `--lr-conversation-item-compact-gap` (default
+`var(--lr-space-2xs)`) — `[part='base']`'s gap while `compact`. Like the active-state pair, both are
+inline `var()` fallbacks at the point of use and never declared on `:host`, so a surrounding list can
+retune every row at once from an ancestor. `[part='content']`'s gap collapses to a flat `0` under
+`compact` with no hatch of its own — there is no smaller step left to retune to. `:host([compact])
+[part='base']` is ordered *before* `:host([active]) [part='base']` (equal specificity), so a row that
+is both compact and active keeps the active background and the promoted excerpt/timestamp contrast.
+
+Plus shared tokens — `--lr-space-xs/-s/-m`, `--lr-radius`,
 `--lr-transition-fast`, `--lr-color-text/-text-quiet/-brand/-brand-quiet/-surface`,
 `--lr-focus-ring-width/-color/-offset`, `--lr-icon-button-size`.
 
@@ -114,5 +149,10 @@ duration of an edit rather than just visually swapping content (a row mid-edit *
 - Setting `editable = false` mid-rename silently discards the in-progress draft (no `lr-rename`
   fires) — a consumer toggling `editable` off (e.g. in response to some other row entering rename
   mode) should not expect the previous edit to be committed first.
+- `compact` is a spacing knob only — it never lowers the rename button's `--lr-icon-button-size`
+  floor. A compact row that still shows a rename button (or slotted `actions` at the same floor)
+  therefore bottoms out at roughly that icon size plus the compact padding, not at the text height.
+  Lowering `--lr-icon-button-size` at an ancestor is the explicit, informed opt-out of the
+  target-size floor; a density flag deliberately won't do it silently on your behalf.
 
 ---

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

@@ -21,8 +21,10 @@ row/column into view via the virtualized list's `active-id`. `highlights` paint
 
 **Properties:** `src` and `name` are strings. `hasHeaderRow: boolean = true` (attribute
 `has-header-row`) controls whether the first parsed row is rendered as a sticky header.
-`anchorKinds` is a readonly `['cell-range']` (this viewer's supported `LyraAnchor.kind` values for
-the shared anchor-target contract).
+`maxHeight: string = ''` (attribute `max-height`) is a CSS length that caps the scrollable body —
+setting it writes `--lr-csv-viewer-max-height` inline on `[part="base"]`. `anchorKinds` is a
+readonly `['cell-range']` (this viewer's supported `LyraAnchor.kind` values for the shared
+anchor-target contract).
 
 **Methods:** `search(query)` resolves the match count via a case-insensitive substring match over
 the same stringified cell values `cell()` renders, ordered row then column (empty/whitespace query
@@ -37,7 +39,18 @@ Enter/Space. `lr-anchor-result` (`detail: { found }`) — fired after an `anchor
 `search()`/`searchNext()`/`searchPrevious()`/`clearSearch()`.
 
 **CSS parts:** `base`, `sheet`, `header-row`, `data-row`, `cell`, `cell-highlight` (a cell covered by
-a `highlights` entry), `rows`, `spinner`, and `error`.
+a `highlights` entry), `rows`, `spinner`, and `error`. `data-row`, `cell` and `cell-highlight` are
+rendered inside the internal `<lr-virtual-list>` and forwarded via `exportparts`, so
+`lr-csv-viewer::part(cell)` reaches them from a consumer stylesheet.
+
+**Themeable custom properties:** `--lr-csv-viewer-max-height` (default `none`) — maximum block size
+of `[part="body"]` before it scrolls internally; also settable via the `maxHeight` property, which
+writes this token inline on `[part="base"]`. `--lr-csv-viewer-highlight-color` (default
+`var(--lr-color-brand)`) — the outline color of a `cell-highlight` cell. The component writes it
+inline (as `var(--lr-color-warning, var(--lr-color-brand))`) on the cell matching
+`activeHighlightId`, since a `[data-active]` selector can't be chained onto the
+`::part(cell-highlight)` the cell reaches this component's stylesheet through; a custom property
+inherits across that boundary instead.
 
 **Optional peer dependency:** install `papaparse` with `pnpm add papaparse`. The registry matches
 `text/csv` and `.csv` filenames.

package/llms/components/lr-data-grid.md

@@ -45,3 +45,11 @@ The focus position is re-clamped whenever `rows`/`columns` shrink, so the grid c
 
 **CSS parts:** `viewport` (the scrolling bordered wrapper), `grid` (the `<table role="grid">`),
 `header` (each sticky `<th>`), `row`, `cell`, `empty` (the loading / no-data cell).
+
+**Themeable custom properties:** `--lr-data-grid-row-selected-bg` (default
+`var(--lr-color-brand-quiet)`) — the background of the selected row's cells. It is an inline `var()`
+fallback at its point of use rather than a `:host` declaration, so it can be set on the element *or
+any ancestor*. It exists because Shadow Parts forbids an attribute selector after `::part()` —
+`::part(row)[aria-selected='true']` is invalid CSS — leaving the library-wide
+`--lr-color-brand-quiet` token as the only prior lever, which repaints every other surface reading
+it. `lr-table` exposes the equivalent knob as `--lr-table-row-selected-bg`.

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

@@ -41,7 +41,10 @@ Enter/Space. `lr-anchor-result` (`detail: { found }`) — fired after an `anchor
 **CSS parts:** `base`, `body`, `table`, `header-row`, `header-cell`, `data-row`, `cell`,
 `cell-highlight` (a `role="cell"` covered by a `highlights` entry; wraps the action button),
 `cell-highlight-action` (the native button filling a highlighted cell — focusable, emits
-`lr-highlight-activate` on click or Enter/Space), `spinner`, and `error`.
+`lr-highlight-activate` on click or Enter/Space), `spinner`, and `error`. `data-row`, `cell`,
+`cell-highlight` and `cell-highlight-action` render inside the internal `<lr-virtual-list>` and are
+forwarded via `exportparts`, so `lr-dataset-viewer::part(cell)` reaches them from a consumer
+stylesheet.
 
 **Exports:** `DatasetTable` is `{ fields: string[]; rows: Record<string, string>[] }`.