@aceshooting/lyra-ui 5.1.0 → 5.2.0

package/llms-full.txt

@@ -71,7 +71,7 @@ module-resolution failure, not a silent no-op — `exports` maps `./components/*
   `lr-bar-chart`, `lr-pie-chart`, `lr-doughnut-chart`, `lr-radar-chart`, `lr-polar-area-chart`,
   `lr-bubble-chart`, `lr-scatter-chart`), `lr-box-plot`, `lr-histogram`, `lr-map`, `lr-graph`,
   `lr-knowledge-graph-explorer`, and `lr-geojson-view`. Those always need their own subpath import.
-  The barrel also re-exports every class and type (127 `Lyra*EventMap` types included), so it is the
+  The barrel also re-exports every class and type (every `Lyra*EventMap` type included), so it is the
   one import that defeats tree-shaking — prefer per-component entries in application code.
 - **`lr-flag`** registers from the barrel, but resolving a flag by `country`/`language` (rather than
   a pre-resolved `src`) additionally needs
@@ -154,17 +154,78 @@ Readonly getters, on every form-associated control: `form`, `labels`, `validity`
 
 ## Theming and design tokens
 
-Two layers, both inherited from `LyraElement` (`internal/tokens.styles.ts`):
+Three layers, and **which one you set decides how far the override reaches**:
 
-1. **`--lr-theme-*`** — the application input layer. Set these to retheme; this is the only supported
-   theming mechanism.
+1. **`--lr-theme-*`** — the application input layer. Declared exactly once, at `:root` in
+   `theme.css`, and never inside any component's shadow styles. Set these to retheme.
 2. **`--lr-*`** — internal tokens. Each reads one `--lr-theme-*` input with a hardcoded fallback
    (`--lr-color-brand: var(--lr-theme-color-brand-fill-loud, #0969da)`), so every component renders
    correctly with no theme configured.
+3. **`--lr-<component>-*`** — per-component properties, for one element at a time. Listed in each
+   component's own section.
+
+### Where an override actually reaches
+
+**A `--lr-*` token is declared on every `lr-*` element's `:host`.** So a `--lr-*` value you set on
+an ancestor is re-declared — and lost — at the first `lr-*` element between that ancestor and the
+component you meant to style. It never reaches anything nested inside another component.
+
+**`--lr-theme-*` inputs are declared only once**, at `:root`, and never inside a component's shadow
+styles — so they inherit normally through every nested shadow root. **Setting a `--lr-theme-*` input
+on a wrapper element is the supported way to retheme one subtree.** Setting a `--lr-*` token there
+only works for that wrapper's direct children.
+
+```css
+/* Reaches everything in the subtree, however deeply nested. */
+.invoice-panel { --lr-theme-color-brand-fill-loud: #7c3aed; }
+
+/* Reaches direct lr-* children only — shadowed at the first nested lr-* host. */
+.invoice-panel { --lr-color-brand: #7c3aed; }
+```
+
+Layer 3 is the exception that proves the rule: a handful of `--lr-<component>-*` escape hatches are
+deliberately left **undeclared** by their component and read only through a `var()` fallback at the
+point of use, precisely so a value set on an ancestor is not shadowed. Each one says so in its own
+section; assume shadowing for anything that doesn't.
+
+**Diagnostic:** if a token override has no effect on a nested component, check which layer you set
+before assuming the component is at fault. A `--lr-*` override that works on a standalone control
+and stops working once you nest that control inside another component is this rule, not a bug.
+
+**There is no way to tell a live `--lr-*` declaration from a dead one without rendering.** A dead
+declaration is byte-identical to a working one in the stylesheet, and nothing in a build reports
+it — a test asserting on stylesheet source text (`expect(source).toContain('--lr-token: …')`)
+passes just as happily when the token is being shadowed at a nested host. Verify with
+`getComputedStyle` on the real element in the real state, and perturb the value deliberately to
+confirm the assertion actually bites.
+
+The same trap has a second form inside a component's own styles: a *declared* value always wins
+over a `var()` fallback arm, and `auto` is a declared value. That is why the exact-height escape
+hatches (`--lr-input-control-height`, `--lr-select-trigger-height`, `--lr-chip-height`, …) are
+undeclared by default rather than set to `auto`. Setting one *to* `auto` is therefore not the same
+as leaving it alone: it wins over the fallback arm and makes the per-size minimum-height floor dead
+code. See each control's own reference page for its exact pair.
+
+### Tokens with a contract attached
+
+- **`--lr-theme-icon-button-size`** (default `2.5rem`) backs `--lr-icon-button-size`, the tappable
+  box of **every** icon-only control in the library — `lr-icon-button` itself, and the
+  expand/clear/toggle affordances inside `lr-date-input`, `lr-combobox`, `lr-input`, and
+  `lr-select`. It is a *floor*, not a fixed size. Keep the resolved value **at or above 24px**
+  (WCAG 2.2 SC 2.5.8 target size); the default leaves headroom. Lowering it below that shrinks
+  every affordance in the library at once.
+- **Aligning your own content next to a checkbox or radio.** `--lr-checkbox-label-indent` /
+  `--lr-radio-label-indent` publish the label offset, but custom properties inherit *down*, not
+  sideways, so a sibling node in your tree cannot read them off the control. Compute the same
+  formula from the `--lr-theme-*` inputs you control:
+  ```css
+  padding-inline-start: calc(
+    min(var(--lr-theme-icon-button-size, 2.5rem), 1.75rem) + var(--lr-theme-space-s, 0.5rem)
+  );
+  ```
 
 **`llms/tokens.md` is the full generated catalog** of every token, its `--lr-theme-*` input, and its
-fallback — consult it rather than guessing a token name. Components additionally expose scoped
-`--lr-<component>-*` properties for one-off overrides, listed in each component's own section.
+fallback — consult it rather than guessing a token name.
 
 ```css
 @import '@aceshooting/lyra-ui/theme.css'; /* optional ready-made light + dark base */
@@ -336,7 +397,7 @@ Not custom elements — infrastructure the components compose. Importable via
   Returns a cleanup function that stops the `autoUpdate` loop — call it in `disconnectedCallback()`.
   Used by `lr-combobox`, `lr-select`, `lr-date-input`, `lr-export-button`, `lr-model-select`,
   `lr-mention-popover`, `lr-tool-call-chip`, `lr-citation-badge`, and `lr-menu`.
-- **`prefix.ts`** — `LYRA_PREFIX = 'lyra'`; `tag(name)` → `` `lr-${name}` ``; `defineElement(name, ctor)`,
+- **`prefix.ts`** — `LYRA_PREFIX = 'lr'`; `tag(name)` → `` `lr-${name}` ``; `defineElement(name, ctor)`,
   an idempotent `customElements.define` that is safe if a module is evaluated twice.
 - **`a11y.ts`** — `nextId(scope)`, a monotonic id generator (`nextId('combobox-list')` →
   `"lr-combobox-list-3"`); `srOnly`, a visually-hidden-but-AT-visible class.
@@ -370,6 +431,67 @@ Not custom elements — infrastructure the components compose. Importable via
 `prepack` and included in `package.json`'s `files` allowlist, so a published tarball always carries
 an up-to-date copy matching its `dist/`.
 
+## When no component fits, file it
+
+First rule out a naming mismatch: check `llms/index.md` for a component covering the same job
+under a different name. Most apparent gaps are discovery failures, not missing components.
+
+Then check the live catalog — one read-only request, no side effects, nothing filed:
+
+```bash
+curl -sS 'https://www.lyra-ui.com/api/v1/components/search?q=kanban+board+swimlane'
+```
+
+It returns the closest components with doc links. Search as many phrasings as you like; this
+endpoint is meant to be used freely, and it is the cheapest way to discover that a "missing"
+component already exists under a name you did not guess.
+
+If nothing fits, report the gap so it can be built — but **ask the user and get their explicit
+agreement first.** Filing sends the user's description to an external service; show them what you
+intend to submit, and never file as a silent side effect of noticing a gap. If the user has not
+said yes, do not send it.
+
+```bash
+curl -sS -X POST https://www.lyra-ui.com/api/v1/feature-requests \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "title": "Kanban board",
+    "description": "Needed a drag-and-drop board with swimlanes for a task view; nothing in the catalog covers it.",
+    "searched_for": ["kanban", "board", "swimlane", "drag drop"],
+    "settled_for": "a hand-rolled div grid with HTML5 drag events",
+    "agent": "claude-code"
+  }'
+```
+
+Accepted fields: `title` (required, ≤120 chars), `description` (required, ≤4000 chars), `use_case`,
+`searched_for` (array of terms tried — the most valuable field, since it records which name was
+expected and that's exactly what makes a component undiscoverable), `settled_for` (what was used
+instead), `agent`, and the optional contact fields `name` (≤120) and `email` (≤200). Anonymous
+submission is the default and is fine — `name`/`email` only add value if the maintainer might
+follow up. Ask the user whether they want to be reachable before adding either one; never invent,
+guess, or reuse an address from context you happen to have (git config, an earlier message, the
+environment). All submissions, including any name/email, are stored privately and shown only to
+the maintainer — never published.
+
+The response includes `matches` (the closest existing components, with doc links — read it, since
+it often answers the gap outright) and an `id`; status is readable later at
+`https://www.lyra-ui.com/api/v1/feature-requests/{id}`. The full schema is at
+`https://www.lyra-ui.com/api/v1/openapi.json`.
+
+**Never include private material.** Submissions leave the user's machine. Describe the component
+generically — no source code, no client or product names, no file paths, no credentials. If the
+need cannot be described without such details, do not file it.
+
+Use the API even when you are working inside the lyra-ui repo itself. It is the only intake path —
+do not write the request into a local file instead, where nothing will pick it up.
+
+Keep the report short and concrete:
+
+- **Name the component you wanted**, in library style (`lr-kanban-board`), so the gap is searchable.
+- **Say what it had to do** in a sentence or two — the behaviour, not your implementation.
+- **List the `lr-*` components you actually checked** and why each fell short. This is what separates
+  a real gap from a naming mismatch, and it is the part only you can supply.
+
 # Form controls & inputs (`components/forms/`)
 
 ## `lr-combobox` / `lr-option`
@@ -396,7 +518,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`),
@@ -457,10 +581,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`
@@ -472,6 +617,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`
@@ -604,6 +761,15 @@ selection change — a native `<select>` doesn't meaningfully distinguish the tw
 **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.
+
 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.
@@ -616,10 +782,28 @@ presentational `<div>`, not a `role="group"`; options with an empty `group` get
 
 **Themeable custom properties:** `--lr-select-trigger-padding`, `--lr-select-trigger-min-height`,
 `--lr-select-font-size`, `--lr-select-expand-size` — all four auto-swapped per `size` (`xs`…`xl`), the same pattern
-`lr-toast-item`'s `--lr-toast-padding`/`--lr-toast-font-size` use. `--lr-select-trigger-height`
-(default `auto`) — unset, it leaves `--lr-select-trigger-min-height` as a floor only, unchanged; set
-it to force an exact trigger height (e.g. to pixel-match a sibling text field in the same row), which
-both floors and caps the trigger at that height.
+`lr-toast-item`'s `--lr-toast-padding`/`--lr-toast-font-size` use.
+
+`--lr-select-trigger-min-height` is live at **every** tier, the default `m` included, where it is
+`2.5rem` — byte-identical to `lr-input`'s and `lr-combobox`'s own `m` floor, so the three controls
+agree at that tier. It used to be dead code: the component declared `--lr-select-trigger-height:
+auto` on `:host`, and a *declared* value (`auto` is one) wins over the `var()` fallback arm that
+the floor lives in, so the floor never applied and four extra specificity rules existed only to
+patch it back for four of the tiers. Those rules are gone.
+
+`--lr-select-trigger-height` pins an **exact** trigger height — both a floor and a cap — e.g. to
+pixel-match a sibling text field in the same toolbar row. It is **undeclared by default**, which is
+exactly what keeps the per-tier floor alive; see "exact-height hatches" under `lr-input`. Because
+the component never declares it, it can be set inline, from an ancestor, or from an outer-tree
+rule. One consequence worth knowing when testing:
+`getComputedStyle(el).getPropertyValue('--lr-select-trigger-height')` now reads `''` rather than
+`'auto'` — assert the rendered `min-block-size`/`block-size` instead of the property string.
+
+`--lr-select-option-active-bg` (default `var(--lr-color-brand-quiet)`) recolors the background of a
+hovered or keyboard-active `[part='option']` row. Not declared on `:host`, so a value set on any
+ancestor is never shadowed — retheme just this row state without hijacking the shared
+`--lr-color-brand-quiet` token every other component's own hover/active state also reads. Same
+knob `lr-combobox`'s own `--lr-combobox-option-active-bg` provides.
 
 **Optional peer deps:** none.
 
@@ -775,17 +959,42 @@ internal native date input.
 the internal `<input>`'s own `blur`, bubbling and composed unlike the native event), `focus`
 (re-dispatched from the internal `<input>`'s own `focus`, for the same reason as `blur`)
 
-**Slots:** `label`, `error` (overrides `errorText`), `hint`
+**Slots:** `label`, `error` (overrides `errorText`), `hint`, plus two adornment slots:
+- `start` — content at the inline-start of the input row, before the text field.
+- `end` — content after the text field and the built-in clear action, and before the calendar
+  toggle, so consumer content never sits outboard of the calendar button.
 
-**CSS parts:** `form-control`, `form-control-label`, `input-wrapper`, `input`, `clear-button`,
+**CSS parts:** `form-control`, `form-control-label`, `input-wrapper`, `input`, `start` and `end`
+(the two adornment-slot wrappers, each `hidden` while nothing is slotted into it), `clear-button`,
 `expand-button`, `expand-icon`, `popup`, `date-picker`, `error`, `hint`
 
 **Themeable custom properties:** `--lr-date-input-padding-block` (default `--lr-space-xs`) and
 `--lr-date-input-padding-inline` (default `--lr-space-s`) — the `input-wrapper`'s padding;
-`--lr-date-input-font-size` (default `inherit`) — the `input` part's font size. All three are
-declared on `:host` and auto-swapped per `size` (`2xs`/`xs`/`s`/`l`/`xl`; `m` keeps the `:host`
-defaults), deliberately matching `lr-input`'s own per-`size` padding/font-size values so a
-same-`size` `lr-input` and `lr-date-input` end up height/density-matched. Plus shared tokens.
+`--lr-date-input-font-size` (default `inherit`) — the `input` part's font size;
+`--lr-date-input-control-min-height` (default `--lr-size-2-5rem`) — the `input-wrapper`'s block-size
+floor. All four are declared on `:host` and auto-swapped per `size`
+(`2xs`/`xs`/`s`/`l`/`xl`; `m` keeps the `:host` defaults), using the same per-`size` values
+`lr-input` uses. Plus shared tokens.
+
+`--lr-date-input-control-height` pins an **exact** `input-wrapper` height (both floors and caps it).
+It is **undeclared by default**, so the row grows to fit its content — see "exact-height hatches"
+under `lr-input`. Pinning it *below* the calendar toggle's 24×24 target is safe: the toggle keeps
+its own `--lr-icon-button-size` floor and simply overflows a short row rather than shrinking, so
+WCAG 2.2 SC 2.5.8 is preserved either way.
+
+**Height parity with `lr-input` is density parity, not pixel parity.** The per-`size` padding and
+font-size scale is shared with `lr-input`, so the two look equally dense at a given `size` — but a
+same-`size` pair does **not** end up the same height, and code that assumes it will be
+disappointed at the small tiers. `[part='input-wrapper']` carries no intrinsic `min-block-size` of
+its own, while `[part='expand-button']` pins `min-block-size: var(--lr-icon-button-size)` that is
+deliberately **not** gated by `size` — the calendar toggle must keep a 24×24 touch target at every
+tier, and `lr-input`'s own password-toggle floors identically. So the row height is pinned
+transitively by that button: at `size="s"` an `lr-input` floors at `1.875rem`/30px, while an
+`lr-date-input` cannot go below roughly 40px plus its padding. Every default value of
+`--lr-date-input-control-min-height` sits below that transitive height, which means the floor is
+inert until you raise it past the button — a lower value changes nothing. To line the two controls
+up exactly, either raise `lr-input`'s floor to meet the date input, or lower
+`--lr-theme-icon-button-size` on a common ancestor (never below 24px).
 
 **Optional peer deps:** none.
 
@@ -1000,12 +1209,40 @@ loud fill token), `--lr-button-outlined-border` (default `--lr-color-border-stro
 `--lr-button-hover-brightness` (default `1.08`, the `:hover` filter intensity),
 `--lr-button-active-scale` (default `0.9875`, the `:active` press-scale, disabled under
 `prefers-reduced-motion`), `--lr-button-spinner-duration` (default `1s`, the `loading` spinner's
-rotation period; forced to `0.001ms` under `prefers-reduced-motion`), and the per-`size`
+rotation period; forced to `0.001ms` under `prefers-reduced-motion`),
+`--lr-button-outlined-fill` (default `transparent`, the `appearance="outlined"` background — also
+variant-independent; set it to tint an outlined button with, say, a faint surface wash behind the
+outline, without a `::part(base)` rule. Note that the `:hover` `filter: brightness()` applies to
+whatever fill is set, so a tinted outlined button visibly brightens on hover where a transparent
+one did not),
+and the per-`size`
 `min-block-size` floors `--lr-button-size-2xs` (`1.25rem`), `--lr-button-size-xs` (`1.5rem`),
 `--lr-button-size-s` (`1.75rem`), `--lr-button-size-m` (`2rem`), `--lr-button-size-l` (`2.5rem`),
 `--lr-button-size-xl` (`3rem`) — each read only by its own `size` tier, and all ignored by
 `appearance="link"`.
 
+**Retuning one `size` tier's geometry, without a `::part(base)` rule.** Four more properties carry
+the active tier's geometry, and every `:host([size='…'])` rule does nothing but re-assign them — no
+per-tier rule ever declares a property on `[part='base']`. Overriding one therefore retunes
+whatever tier is active (e.g. pinning a `size="s"` button into a compact toolbar row), the same
+pattern `lr-input`/`lr-select`/`lr-combobox`/`lr-segmented`/`lr-date-input` follow. Their defaults
+below are the `m` tier's values, because `size` reflects and defaults to `m`, so the `:host`
+declarations *are* the `m` tier:
+
+- `--lr-button-padding-block` (default `--lr-space-xs`)
+- `--lr-button-padding-inline` (default `--lr-space-m`)
+- `--lr-button-font-size` (default `--lr-font-size-m`)
+- `--lr-button-min-height` (default `--lr-button-size-m`) — the active tier's `min-block-size`
+  floor, re-assigned per tier to that tier's own `--lr-button-size-*` token, and used as the
+  fallback when `--lr-button-height` is unset.
+- `--lr-button-height` — an **exact** height (both floor and cap), for pinning the button to a
+  fixed toolbar row. **Undeclared by default**, so the button keeps the active tier's floor and an
+  `auto` height; see "exact-height hatches" under `lr-input`.
+
+`appearance="link"` ignores all five: it is declared after the `size` rules and resets padding,
+font, and both height properties with literals, so an inline link can never take a button-shaped
+box no matter what tier or override is in play.
+
 **Optional peer deps:** none.
 
 ```html
@@ -1044,14 +1281,30 @@ With neither `accessibleLabel` nor `label` set, the name falls back to the local
 app-wide with `registerLyraLocale()` (see `llms/shared.md`); don't rely on the fallback for a
 button whose purpose isn't generic.
 
-**Methods:** `focus(options?)`, `blur()` — forward to the native button.
+**Methods:** `focus(options?)`, `blur()` — forward to the native button. `click()` also forwards to
+the native button, activating it — including this component's own `type="submit"`/`type="reset"`
+handling, since the click goes through the same `<button>` the pointer/keyboard path does.
 
-**Slots:** (default) — custom icon content, forwarded into the inner `lr-icon`'s slot; use it
-instead of `icon` for a glyph outside the built-in set.
+**Slots:** (default) — custom icon content. It is rendered **beside** the `icon` glyph, as a
+sibling of it, not piped through `<lr-icon>`: the internal `<lr-icon>` mounts only when `icon` is
+set, so with `icon` left empty your content is the button's only child. That is what lets a
+complete element — an `<svg>`, an `<img>`, an `<lr-flag>` — render at its own natural aspect ratio
+instead of being forced into a 1:1 box. Setting both `icon` and slotted content renders both, side
+by side; that is a valid composition, not a fallback.
+
+**Migration note:** bare SVG *geometry* (`<path>`, `<circle>`, `<rect>` …) slotted with no `icon`
+set has no SVG parent here and will not paint. Wrap it in an `<lr-icon>`, or in a complete `<svg>`
+of your own.
 
 **CSS parts:** `button`
 
-**Themeable custom properties:** `--lr-icon-button-size` sets both dimensions of the hit target.
+**Themeable custom properties:** `--lr-icon-button-size` (default `2.5rem`) is the **minimum**
+tappable inline and block size of the native button — a floor, not a fixed size. Content larger
+than it grows the button and keeps its own aspect ratio; a small glyph pads out to it. It is a
+library-wide token (declared on `:root` by the token layer, and the shared minimum tappable size
+that several other components size their icon-only controls against), so overriding
+`--lr-theme-icon-button-size` globally resizes all of them together. Keep the resolved value at or
+above 24px — see `llms/shared.md`.
 
 ## `lr-input`
 
@@ -1089,7 +1342,14 @@ form-associated via the same `FormAssociated` mixin as `lr-textarea`. Ships the
 - `name`/`disabled`/`required` (from `FormAssociated`)
 
 **Getters/methods:** `input: HTMLInputElement | null` (the internal native `<input>`, for direct DOM
-access), `focus(options?: FocusOptions)`, `blur()`, `select()`.
+access), `focus(options?: FocusOptions)`, `blur()`, `select()`. Also forwards the full native
+selection/editing surface, mirroring `lr-textarea`'s identical passthrough: `selectionStart: number
+| null` and `selectionEnd: number | null` (readable/writable; `null` both before the internal input
+has rendered and whenever `type` doesn't support selection — only `text`/`search`/`password` do,
+matching the native `<input>`'s own contract), `setSelectionRange(start, end, direction?)`
+(no-op before render, otherwise throws the same native `InvalidStateError` a native `<input>` would
+for an unsupported `type`), and `setRangeText(replacement, start?, end?, selectMode?)` (no-op
+before render; syncs `value` afterward without emitting a user event).
 
 **Events:** native-style composed `input` and `change`, plus `lr-input` (`detail: { value }`,
 fired on every user-driven edit) and `lr-change` (`detail: { value }`, fired on the native
@@ -1108,6 +1368,34 @@ input and built-in actions).
 `--lr-input-font-size`, `--lr-input-control-min-height` — all four auto-swapped per `size`
 (`2xs`…`xl`), the same pattern
 `lr-select`'s `--lr-select-trigger-padding`/`--lr-select-font-size` use.
+`--lr-input-control-height` pins an **exact** outer control-row height (both floors and caps it) —
+for example to pixel-match an `<lr-select>` or `<lr-combobox>` in the same toolbar row. It is
+undeclared by default, leaving `--lr-input-control-min-height` as a floor only and the row free to
+grow.
+
+### Exact-height hatches — the one rule that applies to all of them
+
+Several controls expose the same pair: a per-`size` `*-min-height` **floor**, and an exact
+`*-height` **cap**. The family is `--lr-input-control-height`, `--lr-select-trigger-height`,
+`--lr-combobox-trigger-height`, `--lr-date-input-control-height`, `--lr-button-height`,
+`--lr-known-date-field-height`, and `--lr-chip-height`. Every one of them behaves identically:
+
+- **Each is undeclared by default.** The component reads it only through two `var()` fallbacks —
+  `min-block-size: var(--lr-x-height, var(--lr-x-min-height))` and
+  `block-size: var(--lr-x-height, auto)` — so leaving it unset is what makes the per-tier floor
+  and the content-driven height work at all.
+- **Setting one to `auto` is not the same as leaving it unset.** `auto` is a perfectly valid
+  *declared* value, and a declared value wins over the `var()` fallback arm — so `auto` silently
+  turns the per-tier `*-min-height` floor into dead code, and nothing anywhere reports it. To
+  return a control to default behavior, **remove** the declaration; never neutralize it with
+  `auto`.
+- Because the component itself never declares them, each can be set inline on the element, from an
+  ancestor, or from an outer-tree rule (`lr-input { --lr-input-control-height: 44px }`) — no
+  `::part()` rule needed.
+- **A dead declaration is invisible in source.** There is no way to tell a live `--lr-*`
+  declaration from a shadowed or defeated one without rendering: a test asserting on stylesheet
+  text passes either way. Assert the rendered `min-block-size`/`block-size` via
+  `getComputedStyle` on the real element instead of reading the custom property back.
 
 **Optional peer deps:** none.
 
@@ -1147,8 +1435,9 @@ input), and `lr-clear` (inherited, never fired here).
 alias ever renders.
 
 **Themeable custom properties:** inherited from `lr-input`, identical in meaning —
-`--lr-input-control-min-height`, `--lr-input-padding-block`, `--lr-input-padding-inline` and
-`--lr-input-font-size` (the last three swap per `size`).
+`--lr-input-control-min-height`, `--lr-input-control-height`, `--lr-input-padding-block`,
+`--lr-input-padding-inline` and `--lr-input-font-size` (all but `--lr-input-control-height` swap
+per `size`; that one stays undeclared until you pin an exact row height).
 
 **Known gotchas:**
 - `clearable`/`clear-button`/`lr-clear` are inert: the clear action only renders for
@@ -1190,8 +1479,9 @@ native input's own constraint validation reports `rangeUnderflow`/`rangeOverflow
 `hint`, `error`, plus the inherited, never-rendered `clear-button` and `password-toggle`.
 
 **Themeable custom properties:** inherited from `lr-input`, identical in meaning —
-`--lr-input-control-min-height`, `--lr-input-padding-block`, `--lr-input-padding-inline` and
-`--lr-input-font-size` (the last three swap per `size`).
+`--lr-input-control-min-height`, `--lr-input-control-height`, `--lr-input-padding-block`,
+`--lr-input-padding-inline` and `--lr-input-font-size` (all but `--lr-input-control-height` swap
+per `size`; that one stays undeclared until you pin an exact row height).
 
 **Known gotchas:** the same two as `lr-number-input` — the inert clear/password surface, and `type`
 only being re-forced on connect. The native `type="time"` UI (spinners, AM/PM, picker) is the
@@ -1208,6 +1498,12 @@ synchronous `PhoneNumberAdapter`, or lazily create one from a `libphonenumber-js
 with `loadLibphonenumberAdapter()`. Without an adapter, already-international E.164 input still
 normalizes and validates; national input remains editable with `incomplete` validity.
 
+The country selector keeps the real native `<select>` (localized full country names in its popup,
+native mobile pickers, keyboard type-ahead) but stretches it invisibly over a compact decorative
+trigger showing the selected alpha-2 code plus a design-system chevron — long country names never
+clip the closed control and the adjacent calling code isn't repeated. With `flags`, the trigger
+also shows the selected country's `<lr-flag>`.
+
 **Types:**
 
 ```ts
@@ -1245,6 +1541,15 @@ interface PhoneNumberAdapter {
   precedence over `adapter.countries`.
 - `defaultCountry: string = ''` (attribute `default-country`) — selected when `country` has not been
   set explicitly.
+- `flags: boolean = false` (reflected) — show the selected country's flag in the country trigger as
+  `<lr-flag variant="compact" aria-label="">` (decorative; the native select already announces the
+  country name). The `<lr-flag>` element definition is registered lazily the first time any
+  `lr-phone-input` enables this, so nothing flag-related is bundled while it stays off. Flag
+  *artwork* still follows the standalone `<lr-flag>` contract: install the optional
+  `@aceshooting/lyra-flags` peer and import
+  `@aceshooting/lyra-ui/components/media/flag/flag-peer.js` once; without that registration the
+  trigger simply omits the image. The open popup list stays text-only — a native `<option>` cannot
+  contain elements.
 - `country: string` — current uppercase ISO alpha-2 selection; falls back to `defaultCountry`, then
   the first explicit/adapter country. Changing the country reparses the editable number.
 - `label: string = ''`, `hint: string = ''`, `errorText: string = ''` (attribute `error-text`) —
@@ -1305,8 +1610,11 @@ Programmatic property assignments and form reset/state restoration are silent.
 **Slots:** `label`, `hint`, `error`, `country-prefix` (optional visual before the country selector,
 such as a consumer-owned `<lr-flag>`; no flag package is imported automatically).
 
-**CSS parts:** `form-control`, `form-control-label`, `input-wrapper`, `country-prefix`,
-`country-select`, `calling-code`, `input`, `hint`, `error`.
+**CSS parts:** `form-control`, `form-control-label`, `input-wrapper`, `country-prefix`, `country`
+(the selector region: invisible native select layered over the visual trigger), `country-select`,
+`country-trigger` (visible, `aria-hidden` closed-state box), `flag` (the `<lr-flag>`, only with
+`flags`), `country-code` (selected alpha-2 code, `data-placeholder` when no country exists),
+`expand-icon`, `calling-code`, `input`, `hint`, `error`.
 
 **Themeable custom properties:** shared tokens only. The phone-number input and calling code are
 deliberately `dir="ltr"`/isolated because telephone numbers are algorithmic content; surrounding
@@ -1336,6 +1644,15 @@ phone.adapter = await loadLibphonenumberAdapter(() => import('libphonenumber-js/
 ></lr-phone-input>
 ```
 
+```ts
+// Country flags in the trigger (optional): same peer contract as a standalone <lr-flag>.
+import '@aceshooting/lyra-ui/components/media/flag/flag-peer.js';
+```
+
+```html
+<lr-phone-input label="Mobile number" flags default-country="LU"></lr-phone-input>
+```
+
 **Known gotchas:**
 
 - An adapter's `parse()` method is synchronous because it runs on every keystroke. Load any optional
@@ -1345,8 +1662,15 @@ phone.adapter = await loadLibphonenumberAdapter(() => import('libphonenumber-js/
   as invalid instead of entering form submission.
 - Country names use `Intl.DisplayNames` and fall back to the ISO code; set `PhoneCountry.label` for
   a product-specific name. Calling codes are data, not derived by the component.
-- The component does not import `@aceshooting/lyra-flags`. Compose an optional flag through
-  `country-prefix` and keep it decorative when the adjacent select already announces the country.
+- The component never imports `@aceshooting/lyra-flags` itself, with `flags` or without. `flags`
+  lazily registers only the `<lr-flag>` element; the artwork resolver comes from the consumer's own
+  `flag-peer.js` import (plus the installed peer package), so forgetting either shows a flagless
+  trigger rather than erroring. `country-prefix` remains available for a fully consumer-owned
+  adornment instead.
+- The visible trigger (`country-trigger` and everything inside it) is `aria-hidden` by design; the
+  layered native select is the accessible control. Don't move interactive content into those parts
+  via `::part` styling tricks, and don't expect the flag inside the open popup list — a native
+  `<option>` is text-only.
 
 ---
 
@@ -1381,11 +1705,27 @@ key-up-commit, or when a preset button is clicked, `detail: { start, end }`)
 
 **CSS parts:** `base`, `track`, `range`, `handle-start`, `handle-end`, `presets`, `preset-button`
 
-**Themeable custom properties:** shared tokens only — `--lr-color-border`, `--lr-color-brand`,
+**Themeable custom properties:** mostly shared tokens — `--lr-color-border`, `--lr-color-brand`,
 `--lr-color-surface`, `--lr-shadow` (track/handles), `--lr-opacity-disabled` (`:host([disabled])`
 dimming), plus (for `presets`) `--lr-color-text`, `--lr-color-on-brand` (the active preset
 button's text), `--lr-radius`, `--lr-space-xs/-s`, `--lr-transition-fast`,
-`--lr-focus-ring-*`. No component-local tokens.
+`--lr-focus-ring-*`.
+
+Three component-local properties recolor the **active** preset button independently of the shared
+palette: `--lr-time-range-preset-active-bg` (falls back to `--lr-color-brand`),
+`--lr-time-range-preset-active-border-color` (falls back to `--lr-color-brand`), and
+`--lr-time-range-preset-active-color` (falls back to `--lr-color-on-brand`). Unset, each resolves
+to exactly the token the rule used before they existed, so the default rendering is unchanged.
+
+They exist because the active preset is marked with an attribute on a part, and
+`::part(preset-button)[data-active]` is **invalid CSS** — an attribute selector cannot follow
+`::part()`. Without these, recoloring just the active preset meant hijacking the shared
+`--lr-color-brand`/`--lr-color-on-brand` tokens and repainting everything else that reads them.
+
+They are written as **inline `var()` fallbacks at the point of use, never declared on `:host`** —
+deliberately, because a `:host` declaration would shadow any value an ancestor set. Setting one on
+any ancestor of the `<lr-time-range>` therefore reaches it. (The same technique is used for
+`lr-emoji-picker`'s `--lr-emoji-picker-active-bg`.)
 
 **Optional peer deps:** none.
 
@@ -1541,10 +1881,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
@@ -1736,8 +2103,8 @@ A form-associated single-choice control. Use it alone or inside `lr-radio-group`
 
 **Properties:** `checked`, `disabled`, `required`, `name`, and `value` (all reflected where
 applicable). A selected radio submits its value through `ElementInternals`.
-`effectiveRequired` exposes the required state inherited from a containing radio group. `focus()`
-and `blur()` forward to the internal radio control.
+`effectiveRequired` exposes the required state inherited from a containing radio group. `focus()`,
+`blur()`, and `click()` forward to the internal radio control.
 
 **Events:** native-style composed `input` and `change`, plus `lr-change` with
 `{ checked, value }`.
@@ -1746,6 +2113,14 @@ and `blur()` forward to the internal radio control.
 
 **CSS parts:** `base`, `circle`, `dot`, `label`.
 
+**Themeable custom properties:** `--lr-radio-label-indent` — the inline distance from the control's
+start edge to the start of the label text, i.e. the circle's own floor plus the gap beside it,
+defaulting to `calc(min(var(--lr-icon-button-size), 1.75rem) + var(--lr-space-s))`. The rendered
+gap is derived from it, so the advertised value and the real offset cannot drift; setting it on the
+element (or on `lr-radio` in your own stylesheet) moves the label. Exactly the same knob, defaults,
+purpose, and sideways-inheritance caveat as `--lr-checkbox-label-indent` — see `lr-checkbox` above
+for the formula to align a sibling hint element.
+
 ```html
 <lr-radio name="format" value="json">JSON</lr-radio>
 ```
@@ -1774,6 +2149,23 @@ selected value is submitted under `name` and `required` requires at least one se
 **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.
+
 ## `lr-token-input`
 
 An editable form-associated token list. Enter, comma, or blur commits a token; Backspace removes
@@ -1781,18 +2173,45 @@ the last token. `value` is a `string[]` and repeated values are submitted under
 
 **Properties:** `value`, `label`, `hint`, `errorText` (`error-text`), `placeholder`, `name`,
 `required`, `disabled`, `accessibleLabel` (attribute `aria-label` — forwarded to the internal text
-input), `allowDuplicates` (`allow-duplicates`, default `false`), and `delimiter` (default `','`).
+input), `allowDuplicates` (`allow-duplicates`, default `false`), `editable` (reflected, default
+`false` — see below), and `delimiter: string | null` (default `','` — see below).
 **Slots:** `label`, `hint`, `error`.
-**Events:** `input`, `change`, `lr-add` (`detail: { value }`), and `lr-remove`
-(`detail: { value, index }`).
-**CSS parts:** `form-control`, `form-control-label`, `input-wrapper`, `token`, `remove` (the
+**Events:** `input`, `change`, `lr-add` (`detail: { value }`), `lr-remove`
+(`detail: { value, index }`), and `lr-token-edit`
+(`detail: { value, previousValue, index }` — an existing token was edited in place and committed).
+**CSS parts:** `form-control`, `form-control-label`, `input-wrapper`, `token`, `token-label` (the
+token's text, doubling as the roving-focus edit trigger — rendered only while `editable`),
+`token-editor` (the inline text field that replaces a token's text while it is open for editing —
+rendered only while `editable` and only for the token being edited), `remove` (the
 per-token remove button, floored at the shared `--lr-icon-button-size` tap size around a compact
 glyph), `input`, `hint`, `error`. `focus()` and `blur()` forward to the internal text input.
 
+**`editable` — editing a token in place.** Off by default, in which case the token row renders
+exactly as it does without the feature and stays non-focusable. Turn it on and each token becomes a
+roving tab stop (one Tab stop for the whole row): click, Enter, Space, or F2 opens an inline
+editor on that token; ArrowLeft/ArrowRight move between tokens (swapped under RTL, since they mean
+previous/next *visually*), Home/End jump to the first/last. Inside the editor, Enter commits and
+returns focus to the token, Escape cancels (and is consumed rather than left to bubble, so an
+enclosing dialog or popover does not also close), and blurring commits *without* pulling focus
+back — a blur means the user already aimed focus elsewhere. `lr-token-edit` fires only for an edit
+that actually changed something: a reverted, unchanged, emptied, or (under the default
+`allowDuplicates = false`) duplicate-colliding edit is discarded silently, mirroring how a
+duplicate draft is skipped rather than rejecting the whole entry.
+
+**`delimiter` is nullable, and only a single character acts as a commit key.** It does two separate
+jobs: it splits a committed draft into several tokens, and — *only when it is exactly one
+character* — it is the keystroke that commits the draft. A multi-character delimiter still splits a
+pasted or committed draft, but no keystroke can ever match it, so nothing commits on typing.
+Setting it to `null` disables both, so a token may contain the delimiter verbatim. **`delimiter="null"`
+does not work** — that is the four-character string `null`. Use `delimiter="none"`, `delimiter=""`
+(both of which the attribute converter maps to `null`), or a property binding
+(`.delimiter=${null}`). Removing the attribute restores the `,` default.
+
 **Themeable custom properties:** `--lr-token-input-input-inline-size` (the editable input's
 `flex-basis` inside the wrapped token row; undeclared by default, falling back inline to
-`--lr-size-8rem`) and `--lr-token-input-min-input-inline-size` (default `--lr-size-4rem`, the floor
-that input keeps once tokens have consumed the row).
+`--lr-size-8rem`), `--lr-token-input-min-input-inline-size` (default `--lr-size-4rem`, the floor
+that input keeps once tokens have consumed the row), and `--lr-token-input-editor-inline-size`
+(default `--lr-size-6rem`, the inline size of the inline token editor opened by `editable`).
 
 ## `lr-code-editor`
 
@@ -1875,13 +2294,23 @@ supplied (an explicit empty array still counts as supplied and skips the auto-lo
 When the filtered set reaches 200 items, the grid automatically windows its visible rows while
 preserving the full option count through `aria-setsize`/`aria-posinset`.
 
+Ships the same opt-in `label`/`hint`/`errorText` form-control chrome as `lr-select`/
+`lr-color-picker` (props + matching named slots + `form-control`/`form-control-label`/`hint`/
+`error` CSS parts) — left unset, none of that chrome renders.
+
 **Properties:** the shared form properties `name`, `value`, `disabled`, and `required`, plus
 `groups: EmojiPickerGroup[] = []` (attribute: false) — `EmojiPickerGroup { key, label, emojis:
 EmojiPickerItem[] }`, `EmojiPickerItem { emoji, name, shortcodes? }`; the search field matches `name`
 and every `shortcodes` entry, case-insensitively. Empty (the default, before the auto-loader
 resolves) renders just the search input and the empty state. `accessibleLabel` (`aria-label`)
 forwards a host-supplied accessible name to the internal `role="listbox"` grid; empty falls back to
-the localized default grid label.
+the localized default grid label. `label: string = ''` — visible label rendered above the
+search/grid; unset renders no label chrome. When `label` (or the `label` slot) is set and
+`accessibleLabel`/a host `aria-label` is not, the grid's accessible name switches from the
+localized default to `aria-labelledby` pointing at the visible label. `hint: string = ''` —
+supporting text rendered below the search/grid; unset renders no hint chrome. `errorText: string =
+''` (attribute `error-text`) — validation-error text rendered below the hint (overridden by slotted
+`error` content when provided); unset renders no error chrome.
 
 **Events:** `lr-change` with `detail: { emoji }` (an emoji was picked — click, or Enter/Space on
 the active grid cell; also sets `value`), plus the shared form `input`, `change`, `focus`, and `blur`.
@@ -1894,9 +2323,14 @@ Home/End jump to the first/last item, and Enter/Space picks the active item. The
 the input, with `aria-activedescendant` tracking the active option. Hovering an emoji with the
 pointer also moves the active item to it.
 
-**CSS parts:** `base`, `search` (`role="combobox"`), `grid` (`role="listbox"`, the scroll
-viewport), `group-label`, `emoji` (each emoji's own `role="option"` button), `empty` (shown when
-the search matches nothing). While windowing is active the rows are wrapped in `virtual-spacer`
+**Slots:** `label` (custom label content), `hint` (custom hint content), `error` (custom error
+content, overrides the `errorText` attribute when provided).
+
+**CSS parts:** `form-control` (the outer wrapper around label, `base`, error and hint),
+`form-control-label` (the visible label), `base`, `search` (`role="combobox"`), `grid`
+(`role="listbox"`, the scroll viewport), `group-label`, `emoji` (each emoji's own `role="option"`
+button), `empty` (shown when the search matches nothing), `hint` (the hint message), `error` (the
+error message). While windowing is active the rows are wrapped in `virtual-spacer`
 (full-height scroll spacer), `virtual-row` (one absolutely-positioned row), `virtual-label` (an
 `aria-hidden` spacer standing in for a row's missing `group-label`), and `virtual-items` (the row's
 emoji flex line).
@@ -1913,6 +2347,15 @@ and re-derived only when the resolved pixels can actually change (a token overri
 first render, a theme swap, a root or host font-size change feeding a `rem`/`em` value), never per
 frame.
 
+`--lr-emoji-picker-active-bg` recolors the highlight behind the active/hovered emoji, falling back
+to `--lr-color-brand-quiet` when unset — so the default rendering is unchanged. Hover and
+keyboard-active deliberately share one declaration, so this single hook retints both consistently.
+It exists because `::part(emoji)[data-active]` is **invalid CSS** (an attribute selector cannot
+follow `::part()`), which previously left hijacking the shared `--lr-color-brand-quiet` token — and
+repainting everything else that reads it — as the only way in. Like `lr-time-range`'s preset
+properties, it is written as an inline `var()` fallback at the point of use rather than declared on
+`:host`, so a value set on **any ancestor** reaches it instead of being shadowed.
+
 Two constraints remain. `--lr-emoji-picker-item-size` is clamped up to `--lr-icon-button-size`, the
 shared minimum tappable box: a smaller value does not shrink the button, and the windowed geometry
 follows the clamped, painted size. And windowed rows are absolutely positioned at the row-height
@@ -1951,6 +2394,11 @@ message), `footer`, `submit`, `skip` (only rendered when `skippable`), `empty` (
 no entries), and `unsupported` (the fallback note for a key whose `type` is outside the three
 supported ones).
 
+**Themeable custom properties:** shared tokens only. The footer's disabled `submit`/`skip` buttons
+dim through `--lr-opacity-disabled`, the same library-wide token every other disabled control
+reads — so retuning `--lr-theme-opacity-disabled` keeps this form's disabled state consistent with
+the rest of the UI instead of needing a `::part()` rule here.
+
 # Data display, dashboards & flow canvas (`components/data/`)
 
 ## `lr-sparkline`
@@ -2040,6 +2488,19 @@ KPI/stat card — value + unit + label + optional icon/trend/caption.
   hides `[part="unit"]`, for rendering a loading/status message in place of a numeric value
 - `compact: boolean = false` (reflected) — tighter card padding; same convention as `lr-empty`'s and
   `lr-widget`'s `compact`
+- `appearance: 'card'|'plain' = 'card'` (reflected) — visual chrome, mirroring `lr-card`'s
+  `appearance` vocabulary. `'card'` keeps the bordered, filled, padded box that stretches to fill its
+  parent; `'plain'` removes the border, background, padding, corner radius **and** the
+  `block-size: 100%` stretch, so the stat can sit inline in prose, a toolbar, or a table cell.
+  `plain` wins over `compact` when both are set (there is no padding left to tighten), and it drops
+  `emphasis`'s accent edge — that edge is card chrome — while `emphasis`'s brand value tint still
+  applies. A `plain` stat with a safe `href` swaps the card's border-color/lift hover affordance
+  (invisible with no border) for an underline on `[part="value"]`; the `:focus-visible` ring is
+  unchanged
+- `orientation: 'vertical'|'horizontal' = 'vertical'` (reflected) — layout axis. `'vertical'` stacks
+  label, value, trend, sub and caption. `'horizontal'` lays label, value+unit, trend, sub and caption
+  out on a single wrapping baseline row; `[part="spark"]` and `[part="rows"]` have no sensible place
+  on a text baseline and stay stacked on their own full-width line beneath that row
 
 **Events:** none.
 
@@ -2049,15 +2510,24 @@ slot="spark">`, or other compact trend visual — `lr-stat` only reserves the sl
 render one itself), `sub` (rich sub-line content — overrides the `sub` attribute when slotted content
 is provided)
 
-**CSS parts:** `base` (a `<div>`, or an `<a>` for a safe `href`), `icon`, `label`, `value-row`, `value`, `unit`, `trend`, `sub`, `spark`,
+**CSS parts:** `base` (a `<div>`, or an `<a>` for a safe `href`), `icon`, `label` (carries `hidden`,
+and is collapsed, whenever `label` is empty — a label-less stat leaves no blank line above the
+value), `value-row`, `value`, `unit`, `trend`, `sub`, `spark`,
 `caption`, `rows`, `row`, `row-label`, `row-value` — `[part="value"]` gets `aria-labelledby` pairing
 it with `[part="label"]`'s generated id whenever `label` is non-empty (so tabbing straight to the
 `exactValue`-focusable value still announces e.g. "Revenue $1.2K", not just the bare value); each
 `[part="row-value"]` is paired the same way with its own row's `[part="row-label"]`.
 
-**Themeable custom properties:** shared tokens only (`--lr-color-success/-warning/-danger` drive
-the `variant`-colored value text and up/down trend pill; `--lr-color-brand` drives `emphasis`'s
-accent edge and value tint).
+**Themeable custom properties:** `--lr-stat-trend-good-color` (default `var(--lr-color-success)`)
+and `--lr-stat-trend-good-bg` (default `color-mix(in srgb, var(--lr-color-success) 8%,
+transparent)`) — text/background of `[part="trend"]` when its polarity (per `goodDirection`) is
+"good"; `--lr-stat-trend-bad-color` (default `var(--lr-color-danger)`) and `--lr-stat-trend-bad-bg`
+(default `color-mix(in srgb, var(--lr-color-danger) 8%, transparent)`) — the "bad"-polarity
+counterparts. All four are independent of the headline value's `variant="success"`/`"danger"` tint,
+which keeps reading the shared `--lr-color-success`/`--lr-color-danger` tokens directly — retinting
+the trend pill doesn't also recolor the value, and vice versa. Otherwise shared tokens only
+(`--lr-color-success/-warning/-danger` drive the `variant`-colored value text; `--lr-color-brand`
+drives `emphasis`'s accent edge and value tint).
 
 **Optional peer deps:** none.
 
@@ -2111,13 +2581,42 @@ own "consumer computes/renders" contract rather than assuming addition.
   via the retheme-able `--lr-table-heat-tint-lo`/`-hi` custom properties, matching `lr-heatmap`'s
   own ramp-token convention; `cellStyle` is applied directly to the generated `<td>` via `styleMap` — e.g. a computed heat-tint
   background a `cell()`-returned inner element can't paint into the cell's own padding — omit it for
-  no per-cell style override (the default, unchanged output); `editable` enables double-click
-  editing, `editValue` supplies the editor value, and `editType` selects `text` or `number`
+  no per-cell style override (the default, unchanged output); `editable` enables inline editing —
+  `true` opens a native editor on that cell's double-click (one cell at a time), `'always'` instead
+  renders a persistent editor in every body cell of the column from first paint, for a
+  settings/rate-style column meant to be typed straight into — while `editValue` supplies the editor
+  value and `editType` selects `text` or `number`
+  `cellTitle(row) => string | undefined` is the `title` analogue of `cellStyle`, applied directly to
+  the generated `<td>` — e.g. the untruncated text behind an ellipsized cell, or a formatted
+  timestamp behind a relative one;
   `resizable` adds a focusable separator `[part='resize-handle']` and emits `lr-column-resize` with
   the live width in CSS pixels. Drag it, or use logical ArrowLeft/ArrowRight for 10px steps (mirrored
   under RTL), Shift+Arrow for 50px steps, Home for the minimum, and End for an explicit pixel
   `maxWidth`; explicit pixel `minWidth`/`maxWidth` values bound both input paths. The separator
   exposes its current/minimum/bounded-maximum pixel width through ARIA value attributes.
+- `columns[].editable: boolean | 'always'` — a widening of the original `boolean`, non-breaking.
+  `true` is unchanged: double-click a cell to open its editor, one at a time, Enter commits and
+  closes, Escape cancels and closes, blur-after-change commits. `'always'` renders an editor in
+  every body cell of that column, permanently:
+  - **Focus model.** Each editor is a plain tab stop — no `tabindex` of its own — exactly like the
+    existing row-expand toggle, and stays *outside* the header/row roving-tabindex model. Tab walks
+    down the column; arrow keys still navigate the grid from a row's own roving stop, and act as
+    ordinary caret movement once focus is inside a field. Non-editable columns are unaffected.
+  - **Value binding.** A persistent editor binds its `value` as a **content attribute**, not as the
+    `.value` property, so native dirty-value-flag semantics apply. Trade-off: once the user has
+    typed into a cell, an out-of-band `rows` update to that same cell will **not** visibly replace
+    their draft. An editor the user has not touched still picks up a new `rows` value normally.
+    `lr-cell-edit` remains the only mutation channel — the table never mutates `row`.
+  - **Keys.** Enter commits (emits `lr-cell-edit`) and *keeps focus* in the field, since there is no
+    closed state to fall back to. `change` (blur after a modification) commits, as with `true`.
+    Escape is **not** cancelled and does nothing to the editor — there is nothing to cancel back to
+    — so an ancestor dialog/popover still acts on it.
+  - **Focus across re-sorts and pagination.** Rows are keyed, so a re-sort *moves* the editor's
+    `<input>` (the typed value rides along) and the table restores focus to the same logical cell
+    afterwards. If the focused row leaves the rendered page entirely (pagination, filtering), focus
+    is simply lost rather than yanked to whichever unrelated row now sits in that position.
+  - Each editor keeps its own interpolated `tableEditCell` accessible name (`Edit {column}`), so a
+    column of otherwise-identical inputs is still individually named to a screen reader.
 - `columnsHidden: boolean = false` (attribute `columns-hidden`, reflected) — computed/read-only: true
   when a `priority` column is *actually* hidden right now by the `@container` breakpoints above, or
   `showAllColumns` force-visible mode is currently active. Measured via a `ResizeObserver` on
@@ -2128,6 +2627,13 @@ own "consumer computes/renders" contract rather than assuming addition.
   renders exactly when `columnsHidden` is true — no longer whenever any column merely *declares* a
   `priority` regardless of whether anything is actually hidden
 - `rows: T[] = []` (attribute: false)
+- `layout: 'auto'|'fixed' = 'auto'` (reflected) — a **floor** on the `<table>`'s `table-layout`, not
+  an override. `'fixed'` forces the fixed algorithm even when no column declares a `width`, so every
+  column shares the available width evenly and long cell content is clipped/wrapped instead of
+  stretching its column. The default `'auto'` still *resolves* to `fixed` whenever a column declares
+  a `width`, a column has been drag-resized, or a resize gesture is in flight — column resizing does
+  not work under `table-layout: auto`, so `'auto'` can never mean "never fixed". See the gotchas for
+  the two consequences of the fixed algorithm worth knowing before opting in
 - `sortKey: string = ''` (attribute `sort-key`)
 - `sortDir: 'asc'|'desc' = 'asc'` (attribute `sort-dir`)
 - `rowKey?: (row: T) => string | number` (attribute: false) — derives each row's stable identity for
@@ -2153,7 +2659,20 @@ own "consumer computes/renders" contract rather than assuming addition.
   converter would otherwise treat any attribute value, including the literal string `"false"`, as
   `true`).
 - `loading: boolean = false` (attribute `loading`, reflected) and `loadingLabel: string = ''`
-  (attribute `loading-label`) — renders a busy spinner and suppresses the grid while loading
+  (attribute `loading-label`) — renders busy chrome and suppresses the real rows while loading
+- `loadingAppearance: 'spinner'|'skeleton' = 'spinner'` (attribute `loading-appearance`, reflected) —
+  how `loading` renders. `'spinner'` replaces the whole grid with an indeterminate spinner.
+  `'skeleton'` instead renders the real table — the same `<colgroup>` (declared *and* drag-resized
+  widths included), the same `<thead>`, the filter field and the pagination footer — and fills
+  `<tbody>` with placeholder rows, so a cold load sketches the grid's shape rather than collapsing to
+  a spinner and reflowing when the rows land. Kept as a separate property rather than widening
+  `loading` to a string union, so `?loading=${…}` bindings and `el.loading === true` checks keep
+  working
+- `skeletonRows: number = 0` (attribute `skeleton-rows`) — placeholder row count under
+  `loadingAppearance="skeleton"`. `0` derives the count instead: the normalized `pageSize` when
+  pagination is on (capped at 20, so a large page size can't emit thousands of placeholder cells),
+  otherwise 3. Any positive value is used verbatim and is *not* capped. Ignored entirely under the
+  default spinner appearance
 - `pageSize: number = 0` (attribute `page-size`) — positive values enable controlled pagination;
   zero disables the pagination footer
 - `page: number = 1` (attribute `page`, reflected) — controlled current page
@@ -2177,6 +2696,13 @@ own "consumer computes/renders" contract rather than assuming addition.
 - `emptyDescription: string = ''` (attribute `empty-description`)
 - `noColumnsHeading: string = 'No columns configured'` (attribute `no-columns-heading`)
 - `noColumnsDescription: string = ''` (attribute `no-columns-description`)
+- `emptyCompact?: boolean` (attribute `empty-compact`) — overrides the built-in `[part='empty']`
+  state's `compact` rendering. Tri-state: leave it `undefined` (the default) to keep each empty
+  branch's own built-in default — the two shadow-root-level branches (no columns, no rows) render
+  spacious, while the filtered-to-zero branch, which sits inside `[part='base']` alongside the filter
+  field, renders compact. `empty-compact="false"` forces the spacious rendering everywhere, and is
+  parsed as `false` rather than as mere attribute presence. Has no effect once the `empty` slot is
+  filled
 - `revealColumnsLabel: string = 'Show all columns'` (attribute `reveal-columns-label` — the
   reveal-button's label while `priority`-hidden columns are hidden)
 - `hideColumnsLabel: string = 'Show fewer columns'` (attribute `hide-columns-label` — the same
@@ -2209,7 +2735,12 @@ columns, and `lr-column-resize` (`detail: { key, width }`) on every pointer or k
 The internal filter/cell-editor native inputs' `focus` and `blur` are also re-dispatched from the
 host as bubbling, composed events (the native ones are neither).
 
-**Slots:** none — content comes entirely from `columns`/`rows`.
+**Slots:** `empty` — replaces the built-in empty state on the two *data*-empty branches (no rows at
+all, and filtered/paginated down to zero). Left unfilled, the built-in `[part='empty']` `<lr-empty>`
+renders as this slot's fallback content. The no-columns branch is deliberately **not**
+slot-replaceable: it reports a configuration problem (`noColumnsHeading`), not "this query returned
+nothing", and one slot covering all three would collapse that distinction. Everything else comes
+from `columns`/`rows`.
 
 **CSS parts:** `base`, `table`, `head`, `header-cell`, `row`, `cell`, `more-button`, `sort-icon` (a
 chevron indicator shown on the active sortable header, rotated per `sortDir`), `reveal-columns-button`
@@ -2218,9 +2749,20 @@ column defines `footer`), `footer-row`, `footer-cell`, `row-total-cell` (each bo
 `<td>` holding `rowTotal(row)`, rendered only when `rowTotal` is set — the corresponding footer-row
 cell, holding `grandTotal`, is a `footer-cell` instead, matching every other footer cell),
 `expand-toggle-cell`, `row-expand-toggle`,
-`row-expand-icon`, `expanded-row`, `expanded-cell`, `filter-label`, `filter`, `loading`, and
+`row-expand-icon`, `expanded-row`, `expanded-cell`, `filter-label`, `filter`, `loading` (under
+`loadingAppearance="spinner"` the visible block holding the spinner; under `"skeleton"` the
+visually-hidden `role="status"` node, since the placeholder rows are the visible affordance),
+`skeleton` (each `<lr-skeleton>` placeholder inside a skeleton-mode body cell — the placeholder rows
+and cells reuse the ordinary `row`/`cell`/`row-total-cell` parts, which is exactly what keeps them
+geometrically identical to real rows, so `skeleton` is the part to target for the placeholder's own
+look: `::part(skeleton) { --lr-skeleton-h: 2em; }`), and
 `pagination`, `cell-editor`, `group-row`, `group-cell`, and `resize-handle` (the focusable column
-separator)
+separator). The built-in empty state is addressable rather than fixed: `empty` is the `<lr-empty>`
+host in all three empty states, and it re-exports that element's own inner parts as `empty-base`,
+`empty-icon`, `empty-heading`, `empty-description` and `empty-actions`. Note that the no-columns and
+no-rows states return the empty element as the shadow root's own root, with no `[part='base']`
+wrapper around it — `::part(base)` does not apply in those two states, only in the filtered-to-zero
+one — and that `empty` disappears entirely once the `empty` slot is filled.
 
 **Themeable custom properties:** `--lr-table-max-height` (default `none`; controls the scrollable
 body's `max-block-size`). `--lr-table-heat-tint-lo` (default `var(--lr-color-brand-quiet)`) and
@@ -2228,6 +2770,16 @@ body's `max-block-size`). `--lr-table-heat-tint-lo` (default `var(--lr-color-bra
 for heat-tint mode's per-cell background, consulted only on columns/rows that define `heatValue`;
 `--lr-table-resize-min-width` (default `var(--lr-size-3rem)`) and
 `--lr-table-resize-handle-opacity` (default `0.12`) control resizable-column behavior.
+`--lr-table-row-selected-bg` (default `var(--lr-color-brand-quiet)`) — the background of a row whose
+`aria-selected` is `true`. Like every state-scoped custom property in this library it is an inline
+`var()` fallback at its point of use and is **not** declared on `:host`, so it can be set on the
+element *or on any ancestor* and still reach the rule that reads it. It exists because Shadow Parts
+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-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).
 
 **Optional peer deps:** none.
 
@@ -2267,6 +2819,35 @@ for heat-tint mode's per-cell background, consulted only on columns/rows that de
   [role="slider"]`, **or any custom element** (any tag name containing a hyphen — e.g. a
   `<lr-select>`/`<lr-combobox>` rendered inside a `cell()`), are left alone by the table's own
   delegated `click`/`keydown` handlers instead of triggering `lr-sort`/`lr-row-click`.
+- `layout="fixed"` (and any `'auto'` that resolves to fixed) carries two consequences of the CSS
+  fixed algorithm. With no declared widths the **first** row — the header row included — determines
+  every column's width, so revealing a `priority`-hidden column via
+  `[part='reveal-columns-button']` re-measures and changes *all* of them, not just the revealed one.
+  And `columns[].minWidth`/`maxWidth` are silently ignored by `table-layout: fixed`; declare `width`
+  instead when a specific column needs a specific size.
+- skeleton mode keeps geometry stable only when the browser isn't sizing columns from cell content.
+  Under the default `table-layout: auto`, placeholder cells have no intrinsic width, so the columns
+  re-measure when real content arrives — exactly as they do between any two different data sets. For
+  pixel-identical widths across the load, declare `columns[].width` or set `layout="fixed"`. Either
+  loading appearance keeps exactly one `role="status"` live region announcing the state: every
+  placeholder opts out of `<lr-skeleton>`'s own announcement, so a skeleton table never announces
+  once per placeholder row.
+- `columns[].cellTitle` returning an empty string **or** `undefined` omits the `title` attribute
+  entirely rather than rendering `title=""` — an empty `title` would suppress an ancestor element's
+  own tooltip. The attribute is also suppressed while that cell is in inline-edit mode, so the
+  tooltip can't shadow the editor. Accessibility caveat: some screen readers announce a `<td title>`
+  as the cell's accessible *name*, replacing the cell's content rather than supplementing it (the
+  same caveat `lr-stat`'s `exactValue` carries). Use it for a longer form of what the cell already
+  shows, never for information that exists nowhere else.
+- `editable: 'always'` deliberately does not re-assert a cell's source value once the user has typed
+  into it. That is the native dirty-value-flag behavior the attribute binding buys, and it is the
+  point: a background `rows` refresh cannot silently overwrite an in-progress edit. If you need the
+  opposite — an authoritative external value that always wins — do not use `'always'`; re-key the
+  row (`rowKey`) so the editor is recreated rather than updated, or keep `editable: true` and let
+  the short-lived double-click editor's property binding re-assert. Also note the two things
+  `'always'` intentionally does *not* do: it never sets the roving `tabindex` (its editors are
+  ordinary tab stops, so Tab order in that column interleaves with the grid's two roving stops,
+  the same way the row-expand toggle's already does), and it never cancels Escape.
 
 ---
 
@@ -2317,8 +2898,11 @@ The internal page input's `focus` and `blur` are also bridged as bubbling, compo
 `page-input`, `page-count`, `next-button`, `next-icon`, `live-region`.
 
 **Themeable custom properties:** `--lr-pagination-control-size` and
-`--lr-pagination-font-size` (both default from `size`), plus shared color, spacing, border, radius,
-disabled-opacity, and focus-ring tokens.
+`--lr-pagination-font-size` (both default from `size`), `--lr-pagination-control-padding` (default
+`var(--lr-space-xs)`) — inner padding of the previous/next buttons and the page input, deliberately
+uniform across every `size` tier because the control's outer footprint is already fixed by
+`--lr-pagination-control-size`, so this only adjusts the icon/digit inset — plus shared color,
+spacing, border, radius, disabled-opacity, and focus-ring tokens.
 
 **Optional peer deps:** none.
 
@@ -2530,6 +3114,16 @@ focus; it continues to emit `lr-cell-click` and leaves selection state consumer-
   measured `clientWidth` on every draw/resize instead of the fixed `cell-size`, so the grid actually
   fills the available width; now applies to calendar mode as well as matrix mode — see gotchas for
   the default, non-`fit-to-width` behavior)
+- `maxCellSize?: number` (attribute `max-cell-size`) — ceiling, in CSS px, on the cell size
+  `fitToWidth` derives from the host width, in **both** modes. Exists because `fitToWidth` divides
+  the *whole* host width across the grid, so a 5-week calendar or a 3-column matrix in a wide pane
+  produces enormous blocks; capping them keeps a cell a cell
+- `minCellSize?: number` (attribute `min-cell-size`) — the mirror floor, in CSS px, so a year-long
+  calendar in a narrow pane keeps legible, hit-testable cells and overflows its host instead of
+  collapsing to hairlines. It can only *raise* the built-in `4`px floor, never lower it: a value
+  below `4` normalizes to `4`. When both clamps are set and `maxCellSize < minCellSize`, the ceiling
+  wins. For both: a non-finite value, or an empty attribute, means unset rather than `0`, and unset
+  (the default) reproduces the unclamped fit-to-width behavior exactly
 - `valueLabel: string = 'value'` (attribute `value-label`)
 - `scale: 'linear' | 'sqrt' = 'linear'` — governs both modes: in matrix mode, `'sqrt'` compresses the
   color ramp via `sqrtStep()` instead of mapping linearly; in calendar mode, the default `'linear'`
@@ -2563,7 +3157,12 @@ focus; it continues to emit `lr-cell-click` and leaves selection state consumer-
   its low DOM footprint.
 - `cellText?: (pos: MatrixCellPos | CalendarCellPos, value: number) => string` (attribute: false) —
   formats the per-cell hover tooltip and keyboard live-region announcement text; receives the cell
-  position (`{ row, col }` in matrix mode, `{ week, weekday }` in calendar mode) and its value.
+  position (`MatrixCellPos { row, col }` in matrix mode, `CalendarCellPos { week, weekday, date }` in
+  calendar mode) and its value. `CalendarCellPos.date` is a **required** ISO `yyyy-mm-dd` string,
+  present for every grid position — including a sparse gap position with no matching entry in `days`
+  at all, which still sits on a real calendar day (that case simply reports the `-1` "no data" value
+  alongside it). It lets a callback key off the date without re-deriving the grid's own
+  anchor-week arithmetic; `MatrixCellPos` is unchanged, and so is `lr-cell-click`'s detail.
   Unset (the default) falls back to the built-in English "Row X, Col Y: value" (matrix) / "Jan 15:
   value" — short month + day, **not** a weekday abbreviation (calendar) — template. Additive, not
   breaking.
@@ -2610,10 +3209,14 @@ focus; it continues to emit `lr-cell-click` and leaves selection state consumer-
   interpolate continuously into `colorSteps.length` buckets instead. Unset (the default, or fewer
   than 2 entries) keeps today's 2-endpoint interpolation exactly.
 - `legendStops?: HeatmapLegendStop[]` (attribute: false) — `HeatmapLegendStop { value: number;
-  color: string; label?: string }`: a discrete legend key rendered **instead of** the
+  color?: string; label?: string }`: a discrete legend key rendered **instead of** the
   `--lr-heatmap-scale-lo`/`-hi` gradient bar and its `[part="legend-lo"]`/`[part="legend-hi"]`
   endpoint labels — one `[part="legend-stop"]` per entry, in array order, each a
   `[part="legend-swatch"]` filled with that entry's `color` plus a `[part="legend-stop-label"]`.
+  `color` is optional: omit it (or pass an empty string) for a **caption-only** stop, which renders
+  its `[part="legend-stop-label"]` alone with no `[part="legend-swatch"]` element in the DOM at all —
+  so a leading "0" or trailing "more" caption around a run of colored stops doesn't leave an empty
+  swatch box in the row.
   A stop's label defaults to the component's own locale-aware numeric formatting of `value`, so an
   explicit `label` is only needed when the number isn't the right caption ("none", "≥ 90%"). Exists
   for the consumer who supplies `cellColor`: because that callback overrides a cell's color
@@ -2639,7 +3242,9 @@ button), `tooltip` (hover tooltip, positioned over the hovered cell),
 `live-region` (visually-hidden `role="status" aria-live="polite"` element announcing the
 keyboard-focused cell), `legend`, `legend-lo`, `legend-hi` (both omitted, along with the gradient
 bar between them, while `legendStops` is supplied), `legend-stop` (one per `legendStops` entry),
-`legend-swatch` (that stop's color chip), `legend-stop-label` (that stop's text),
+`legend-swatch` (that stop's color chip, not rendered at all for a caption-only stop),
+`legend-stop-label` (that stop's text), `legend-value-label` (the trailing `valueLabel` caption that
+closes the legend row, present in both the gradient and the `legendStops` branch),
 `legend-annotation` (one per labeled `annotations` entry)
 
 **Themeable custom properties:** `--lr-heatmap-scale-lo` (default `#cde2fb`),
@@ -2704,6 +3309,11 @@ same color as `--lr-heatmap-focus-ring-color`).
   width, so a container-resize redraw is a geometric no-op; the stylesheet's
   `canvas { inline-size: 100% }` is also dead code in that case, since `draw()` unconditionally sets
   an inline `canvas.style.width/height` that wins over it.
+- `maxCellSize`/`minCellSize` are no-ops without `fit-to-width` — an explicit `cellSize` is an exact
+  request and is never clamped. And the canvas is sized *from the clamped* cell size, so a capped
+  grid deliberately leaves the host's remaining width unfilled: the canvas simply ends early rather
+  than stretching to fill. Position it with ordinary CSS on the host if you want it centered or
+  end-aligned.
 - the host is `role="group"` (not `role="img"`) with a dimensions+range summary `aria-label`
   (calendar mode: a day-count + range summary instead) — `[part="canvas"]` inside it is a real
   focusable, keyboard-operable, per-cell-interactive control (roving arrow-key focus,
@@ -2758,6 +3368,12 @@ mapping is readable without hovering each cell.
   filtering legend). Because it only repeats the category names `[part="base"]` already announces
   through its `role="img"` summary, the legend is `aria-hidden` — visible on screen, announced
   exactly once — and it wraps onto further rows in a narrow allocation rather than overflowing
+- `markerLabel?: string` (attribute `marker-label`) — names what an item's `marker` *means* (e.g.
+  `"Subagent"`). Setting it does two things: with `showLegend` on it adds one trailing
+  `[part="legend-item"]`, whose `[part="legend-marker-swatch"]` reproduces the cell's own marker
+  treatment, and it adds the marker to the auto-generated `aria-label` summary, which is otherwise
+  per-category only. The marker count is reported as its own clause rather than folded into any
+  category's count. Unset (the default) changes nothing: no extra legend row, no extra summary clause
 
 **Events:** none.
 
@@ -2768,13 +3384,19 @@ by its category), `marker` (the small bottom marker on a cell whose item sets `m
 `tooltip` (the hover tooltip showing the hovered item's label, hidden until a cell is hovered),
 `legend` (the static category key rendered below the strip when `showLegend` is set — `aria-hidden`,
 as it repeats the strip's own `aria-label`), `legend-item` (one swatch + label pair, one per
-`categories` entry), `legend-swatch` (the color chip, matching that category's cell color),
-`legend-label` (the category's `label`, or its `key` when unset).
+`categories` entry, plus one trailing marker row when `markerLabel` is set), `legend-swatch` (the
+color chip, matching that category's cell color), `legend-marker-swatch` (the marker row's chip
+instead: a neutral chip carrying the same bottom bar a `marker: true` cell paints, in the same
+`--lr-sequence-strip-marker-color`), `legend-label` (the category's `label`, or its `key` when
+unset).
 
 **Themeable custom properties:** `--lr-sequence-strip-height` (default `1.5rem` — the strip's
 block-size), `--lr-sequence-strip-marker-color` (default `var(--lr-color-text)` — the
-`[part="marker"]` fill), and `--lr-sequence-strip-legend-swatch-size` (default `0.625rem` — the
-`[part="legend-swatch"]` chip's inline- and block-size); the tooltip also consumes shared tokens
+`[part="marker"]` fill, and of the marker legend row's bar), `--lr-sequence-strip-legend-swatch-size`
+(default `0.625rem` — a legend swatch's inline- and block-size, category and marker rows alike), and
+`--lr-sequence-strip-legend-marker-bg` (default `var(--lr-color-surface-raised)` — the neutral chip
+background behind the marker legend row's bar; it stands in for "any cell", so it deliberately
+matches no category color); the tooltip also consumes shared tokens
 `--lr-color-surface`, `--lr-color-text`, `--lr-font-size-xs`, `--lr-radius`, and `--lr-shadow`, and
 the legend consumes `--lr-space-2xs`, `--lr-space-xs`, `--lr-space-s`, `--lr-font-size-xs`,
 `--lr-color-text-quiet`, and `--lr-radius-xs`.
@@ -2830,18 +3452,34 @@ deeply-nested node's own shadow root still reaches it).
   `[part="base"]` element. The component forwards a host `aria-label` to that semantic element when
   `label` is empty; `label` takes precedence when both are set. External `aria-labelledby` idrefs
   are not forwarded across the shadow boundary.
+- `reorderable: boolean = false` (reflected) — opts into keyboard reordering. Unset, no `lr-reorder`
+  is ever emitted, Ctrl/Cmd+Arrow behaves exactly like a plain Arrow press, and the internal live
+  region is not rendered at all.
 
 **Keyboard:** ArrowDown/ArrowUp move the roving focus to the next/previous *visible* node.
 ArrowRight expands a collapsed node (focus stays put; a second ArrowRight then steps into the first
 child) or moves into an already-expanded node's first child. ArrowLeft collapses an expanded node, or
 moves focus to its parent. Home/End jump to the first/last visible node. Enter/Space activate
-`select()` on the focused node.
+`select()` on the focused node. While `reorderable`, **Ctrl/Cmd**+ArrowUp/ArrowDown moves the focused
+node within its own parent's child list instead of navigating. Ctrl/Cmd rather than Alt: Alt+Arrow is
+browser back/forward on Windows and Linux. ArrowUp/ArrowDown are not direction-sensitive, so this
+binding is deliberately **not** RTL-swapped — "down" always means later in the sibling list.
 
 **Methods:** `expandAll()`, `collapseAll()` (both recursive, properly sequenced around Lit's render
 cycle).
 
-**Events:** none dispatched directly (see `lr-tree-node` below — they bubble up and are also
-observed internally to keep the roving `activeId` in sync with clicks).
+**Events:** `lr-reorder` (`detail: { id, parentId, fromIndex, toIndex }`, only while `reorderable`).
+Like every other event here it is a **request**: `data` is host-owned and is never mutated by this
+component, so nothing moves until the host reassigns a reordered `data` — focus then follows the
+moved node. `parentId` is `null` for a top-level item, and `fromIndex`/`toIndex` are **sibling-scoped
+indices**, not positions in the flattened visible list. The move is constrained to one sibling list
+and never fires at a subtree boundary, so a reorder can never become a reparent: Ctrl+ArrowDown on
+the last child of a subtree is ambiguous (the visually next row is a top-level uncle, so "move down"
+could mean either "swap with the next sibling" — there is none — or "reparent up a level"), and
+reparenting is a structural edit with no keyboard affordance distinguishing the two. Such a request
+is simply not made: no event, no announcement, focus stays put. Otherwise this element dispatches
+nothing directly (see `lr-tree-node` below — those bubble up and are also observed internally to keep
+the roving `activeId` in sync with clicks).
 
 **Slots:** default (holds the `<lr-tree-node>` elements it manages).
 
@@ -2925,6 +3563,8 @@ indentation), plus the shared tokens listed above.
 - row enrichment is intentionally structured rather than an unrestricted renderer: use `icon`,
   `label`, `description`, `badge`, and `accessibleLabel`. This keeps the host as the single
   `role="treeitem"` interaction target and preserves the APG keyboard model.
+- `lr-file-tree` does **not** forward `reorderable`, and deliberately so: its `TreeItem[]` is derived
+  from `nodes` on every render and keyed by filesystem path, an order it does not own.
 
 ---
 
@@ -2991,8 +3631,21 @@ with a console warning), `top-start`, `top-end` (floating corner overlays), `bot
 `live-region`, `edge-list` (a visually hidden list of every edge).
 
 **Themeable custom properties:** `--lr-flow-canvas-grid-size` (default `8px`, dotted background
-spacing), `--lr-flow-canvas-march-duration` (default `var(--lr-transition-ambient)`, running-edge
-march animation duration).
+spacing — the canvas also writes it inline as `${grid}px` from the `grid` property, which wins over
+the stylesheet fallback whenever a grid is in effect), `--lr-flow-canvas-march-duration` (default
+`var(--lr-transition-ambient)`, running-edge march animation duration), and
+`--lr-flow-canvas-node-current-outline-color` (default `var(--lr-color-brand)`) — the outline color
+of the current (`aria-current`) node. Like every state-scoped custom property in this library 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(node)[aria-current='true']` is invalid CSS — so the current node could otherwise
+only be restyled by overriding the library-wide `--lr-color-brand` token, repainting everything else
+that reads it. The same restriction motivates three more state-scoped outline colors:
+`--lr-flow-canvas-node-connect-invalid-outline-color` (default `var(--lr-color-danger)`) — outline of
+a node that is an invalid connect-gesture drop target; `--lr-flow-canvas-node-connect-target-outline-color`
+(default `var(--lr-color-brand)`) — outline of a node that is a valid connect-gesture drop target; and
+`--lr-flow-canvas-drop-active-outline-color` (default `var(--lr-color-brand)`) — outline of the
+viewport itself while a palette item is dragged over it (`droppable`).
 
 **Optional peer deps:** none.
 
@@ -3045,6 +3698,8 @@ owns none of that.
 - `statusDetail: string = ''` (attribute `status-detail`) — appended to the status line
 - `durationMs: number | null = null` (attribute `duration-ms`) — formatted into the status line
 - `selected: boolean = false` (reflected)
+- `compact: boolean = false` (reflected) — tighter card padding for dense canvases and palette
+  previews; the border, background, shadow and the `selected`/`status="running"` treatments all stay
 - `inputs: FlowHandle[] = [{ id: 'in' }]`, `outputs: FlowHandle[] = [{ id: 'out' }]` (attribute:
   false) — `FlowHandle { id: string; label?: string }`
 - `orientation: 'horizontal' | 'vertical' = 'horizontal'` (reflected) — which physical edge handles
@@ -3055,10 +3710,24 @@ owns none of that.
 **Slots:** default (body content), `icon` (leading header glyph), `header` (replaces the built-in
 heading row entirely), `toolbar` (action row at the block-end edge).
 
-**CSS parts:** `base`, `header`, `icon`, `heading`, `status` (never color-only — always paired with
-text), `progress`, `body`, `toolbar`, `handle` (every handle dot), `handle-input`, `handle-output`.
-
-**Themeable custom properties:** `--lr-flow-node-min-inline-size` (default `11rem`).
+**CSS parts:** `base` (the row wrapping the input handles, the card and the output handles — it
+carries no card chrome of its own), `card` (the bordered, filled node card), `header`, `icon`,
+`heading`, `status` (never color-only — always paired with text), `progress`, `body`, `toolbar`,
+`handle` (every handle dot), `handle-input`, `handle-output`.
+
+**Themeable custom properties:** `--lr-flow-node-min-inline-size` (default `11rem`),
+`--lr-flow-node-compact-padding` (default `var(--lr-space-xs)`) and `--lr-flow-node-compact-gap`
+(default `var(--lr-space-2xs)`) — `[part="card"]`'s padding and row gap while `compact` — and
+`--lr-flow-node-selected-border` (default `var(--lr-color-brand)`) — the card's border color while
+`selected`. Like the other state-scoped custom properties here they are inline `var()` fallbacks at
+their point of use rather than `:host` declarations, so they can be set on the element *or any
+ancestor* (a canvas retunes every card at once); overriding the selection color otherwise means
+hijacking the library-wide `--lr-color-brand` token and repainting everything else that reads it.
+`--lr-flow-node-running-border` (default `var(--lr-color-brand)`) — the card's border color while
+`status="running"`, independent of `--lr-flow-node-selected-border` so a consumer can retint just one
+of the two states without the other following along — and `--lr-flow-node-running-glow` (default
+`var(--lr-color-brand-quiet)`) — the box-shadow color of the running-state ring around the card, and
+the pulse keyframes' peak color.
 
 **Optional peer deps:** none.
 
@@ -3071,6 +3740,11 @@ text), `progress`, `body`, `toolbar`, `handle` (every handle dot), `handle-input
   reduced-motion exception every animated surface in this library follows.
 - `status` drives a status chip with a localized label plus `statusDetail`/`durationMs`, never a
   color-only indicator.
+- All card chrome lives on `[part="card"]`, not `[part="base"]` — `base` is only the flex row that
+  holds the input handles, the card and the output handles. Style the box through `::part(card)`.
+- `--lr-flow-node-min-inline-size` was previously overridden by a duplicate declaration and had no
+  effect. It now sets the card's minimum inline size again, so a node that was relying on the card
+  collapsing below `11rem` will render wider than it used to.
 
 ---
 
@@ -3125,16 +3799,23 @@ no editing commands live here.
 - `for: string = ''` — id of the target `lr-flow-canvas`; empty resolves to the nearest ancestor
 - `orientation: 'vertical' | 'horizontal' = 'vertical'` (reflected) — button-cluster layout axis
 - `hideLock: boolean = false` (attribute `hide-lock`) — omits the lock/unlock toggle button
+- `appearance: FlowControlsAppearance = 'card'` (reflected) — `'card' | 'plain'`; `'plain'` drops
+  `[part="base"]`'s border, background, padding, corner radius and its floating-surface `box-shadow`,
+  for a cluster placed in a host toolbar or panel that already draws its own surface. There is
+  deliberately no `compact`: the padding is already the smallest spacing step and the only remaining
+  room is the buttons' `--lr-icon-button-size` hit-area floor
 
 **Events:** none dispatched directly — each button calls the resolved canvas's own `zoomIn()`/
 `zoomOut()`/`fit()`, or toggles its `locked` property.
 
 **Slots:** default — extra host buttons appended to the cluster, styled by the same group.
 
-**CSS parts:** `base` (the `role="group"` wrapper), `zoom-in`, `zoom-out`, `fit`, `lock` (omitted
-when `hideLock`).
+**CSS parts:** `base` (the `role="group"` wrapper; drops its floating-surface chrome under
+`appearance="plain"`), `zoom-in`, `zoom-out`, `fit`, `lock` (omitted when `hideLock`).
 
-**Themeable custom properties:** shared tokens only.
+**Themeable custom properties:** shared tokens only — `--lr-icon-button-size` (each button's minimum
+hit area, unchanged by `appearance`), `--lr-shadow`, `--lr-color-surface`, `--lr-color-border`,
+`--lr-radius`, `--lr-space-2xs`, `--lr-focus-ring-width`/`-color`/`-offset`.
 
 **Optional peer deps:** none.
 
@@ -3148,6 +3829,10 @@ when `hideLock`).
 - `for` resolution is identical to `lr-flow-minimap`/`lr-flow-run-overlay`: an explicit id, else
   the nearest ancestor canvas — none of the three companions import `LyraFlowCanvas` as a value, only
   its types, so registration order between them and the canvas never matters.
+- `appearance="plain"` drops the `box-shadow` along with the border and background — unlike most
+  `plain` escapes in this library, which only reset the border/background/padding/radius. A lift
+  shadow with no surface under it reads as a stray smudge, so the whole floating-surface treatment
+  goes together (same as `lr-flow-run-overlay`'s `plain`).
 
 ---
 
@@ -3164,6 +3849,10 @@ strip. Does not execute, poll, or time anything — pure pushed state; `duration
 - `hideSummary: boolean = false` (attribute `hide-summary`) — omits the "{done} of {total} steps
   complete" strip, keeping only the decoration push
 - `label: string = ''` — accessible name for the summary strip
+- `appearance: 'card'|'plain' = 'card'` (reflected) — `'plain'` removes the border, background,
+  shadow, padding and radius, so a summary strip dropped straight into a host toolbar that already
+  draws its own frame does not double it. `'card'` is the standalone floating-strip presentation and
+  is unchanged.
 
 **Events:** none dispatched directly.
 
@@ -3313,6 +4002,14 @@ 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`.
+
 ## `lr-calendar`
 
 Responsive month calendar with event markers and an agenda view.
@@ -3347,7 +4044,11 @@ the next button), `nav-glyph` (the chevron, `scaleX(-1)`-mirrored under RTL), `t
 
 **Themeable custom properties:** `--lr-calendar-day-min-block-size` (default `var(--lr-size-6rem)`)
 and `--lr-calendar-day-min-block-size-narrow` (default `4rem`, applied at container inline-size
-≤ 28rem).
+≤ 28rem), and `--lr-calendar-day-selected-bg` (default `var(--lr-color-brand-quiet)`) — background of
+a selected (`data-selected="true"`) day cell. Component-scoped indirection over the shared
+`--lr-color-brand-quiet` token, so a consumer can retint the persistent selected-day highlight
+without also recoloring `[part='nav']:hover`/`[part='agenda-event']:hover`, which read that shared
+token directly for a visually distinct purpose (transient hover feedback).
 
 **Gotcha:** month-view `[part='event']` markers are a mouse-only quick-select affordance — they sit
 inside the day `<button>`, which may not contain focusable descendants. Agenda view renders each
@@ -3441,6 +4142,15 @@ the real unmasked value).
 an entry's value text and buttons), `value` (carries `data-masked`), `reveal-button`, and
 `copy-button`.
 
+**Themeable custom properties:** `--lr-env-list-reveal-active-bg` (default
+`var(--lr-color-brand-quiet)`) and `--lr-env-list-reveal-active-border` (default
+`var(--lr-color-brand)`) — the background and border color of a pressed (revealed) reveal toggle.
+Both are inline `var()` fallbacks at their point of use rather than `:host` declarations, so either
+can be set on the element *or any ancestor*. They exist because
+`::part(reveal-button)[aria-pressed='true']` is invalid CSS — Shadow Parts forbids an attribute
+selector after `::part()` — so restyling the pressed state otherwise required overriding the
+library-wide brand tokens.
+
 ## `lr-document-library`
 
 Controlled searchable and filterable document inventory with versions, tags, owners, freshness,
@@ -3545,12 +4255,39 @@ auto-inserted between each adjacent pair.
   the panel's clamped width or `data-collapse-state`, see below).
 - `railWidth: string = '3.5rem'` (attribute `rail-width`) — the fixed CSS length the collapsing panel
   clamps to in `'rail'` state.
-- `railBreakpoint: number = 640` (attribute `rail-breakpoint`, px) — below this container width (a
-  `ResizeObserver` on `[part='base']`, active only while `collapse !== 'none'`), the collapsing panel
-  switches from its normal drag-resizable percent width to the fixed `railWidth`.
-- `floatBreakpoint: number = 400` (attribute `float-breakpoint`, px) — below this narrower container
+- `railBreakpoint: number | string = 640` (attribute `rail-breakpoint`) — below this width, the
+  collapsing panel switches from its normal drag-resizable percent width to the fixed `railWidth`.
+  Accepts a bare pixel number (`640`, `rail-breakpoint="640"` — the original form) or a CSS length
+  string: `'640px'`, `'68.75rem'`, `'3em'`. Under the default `collapseBreakpointBasis='container'`
+  it is compared against this component's own measured `[part='base']` inline size (a
+  `ResizeObserver`, active only while `collapse !== 'none'`), and `rem` resolves against the
+  document root's **computed** font size while `em` resolves against this element's own; the length
+  is re-resolved on every measurement, never cached. Anything the grammar rejects — `''`, `'auto'`,
+  garbage, a non-finite number, and deliberately `%`, `vw`/`vh`, `calc()` and `var()` — falls back
+  to the `640` default rather than switching the feature off (unlike `orientationBreakpoint`, this
+  breakpoint has a documented default to fall back to). A negative length is floored at `0`, i.e.
+  never crossed. Must stay above `floatBreakpoint` — an inverted pair is sanitized by raising this
+  one to match, collapsing the `'rail'` band away rather than reporting a wide container as
+  collapsed.
+- `floatBreakpoint: number | string = 400` (attribute `float-breakpoint`) — below this narrower
   width, the collapsing panel instead becomes an absolutely-positioned overlay ("floating card") on
   top of the other pane(s), removed from the normal flex flow; the sibling(s) take the full width.
+  Same accepted forms, basis, and sanitization as `railBreakpoint`; an unparseable value falls back
+  to the `400` default.
+- `collapseBreakpointBasis: 'container'|'viewport' = 'container'` (reflected, attribute
+  `collapse-breakpoint-basis`) — which box `railBreakpoint`/`floatBreakpoint` are measured against.
+  Unset, behavior is identical to before this property existed. `'container'` observes this
+  component's own `[part='base']` inline size via `ResizeObserver` and compares strictly `<`;
+  `'viewport'` evaluates `matchMedia('(max-width: <breakpoint>)')` for each of the two thresholds,
+  which is inclusive (`<=`) — native `max-width` semantics, deliberately, so the crossing point
+  matches a CSS `@media` rule authored with the same length exactly. Use `'viewport'` to collapse in
+  step with a page-level responsive layout (a shell whose own `@media` rules restack at the same
+  width) rather than with this split's own allocation; it is also what lets the browser resolve a
+  `rem` breakpoint with real `@media` semantics (against the *initial* font size, ignoring an
+  `html { font-size }` override). Both bands are classified from both queries together on every
+  change, so a fast resize crossing both thresholds at once still lands on one correct state and
+  fires `lr-split-collapse-change` once; under `'viewport'` the first paint is already correct — no
+  `ResizeObserver` round-trip — and that initial state is not announced as a transition.
 - `collapseState: 'wide'|'rail'|'floating'` (reflected, attribute `collapse-state`) — a public
   accessor with force/auto semantics mirroring `<lr-app-rail>`'s `mode`: normally derived
   automatically from the measured container width, but assigning it a concrete value pins it there
@@ -3636,6 +4373,21 @@ the visually-adjacent panel).
   `disconnectedCallback`) is solid and safe to rely on.
 - `orientationBreakpoint` shares its `[part='base']` `ResizeObserver` with `collapse` (one observer,
   not two) — arming logic covers either feature being opted into independently.
+- **Switching a basis moves the crossing point by exactly 1px.** Container basis compares strictly
+  `<` against a measured width; viewport basis asks `matchMedia('(max-width: …)')`, which is
+  inclusive (`<=`). So at a breakpoint of `640`, a container-basis split is still `'wide'` at 640px
+  while a viewport-basis one has already collapsed. This is deliberate on both sides: `<` is the
+  right comparison for "how much room do I actually have", and `<=` is what a CSS `@media` rule with
+  the same length does, which is the whole point of the viewport basis.
+- `collapseBreakpointBasis='viewport'` does **not** drop the `ResizeObserver` the way the
+  orientation feature's viewport basis does. The measured width it feeds is still read by a
+  container-basis `orientationBreakpoint` and by the `collapseState = 'auto'` release path, which
+  re-derives from the current measured width. Collapse's basis changes only *which values* the
+  classification consults, never whether the split measures itself.
+- `railBreakpoint`/`floatBreakpoint` are typed `number | string`. Authored as attributes they read
+  back as **strings** (`el.railBreakpoint === '640'`, not `640`) — the same value, a different type.
+  Compare with `Number(el.railBreakpoint)` rather than `===`, or assign the property directly when a
+  numeric identity matters.
 - **Picking a basis.** `orientationBreakpointBasis='container'` (the default) observes the
   component's own allocated inline size, so it fits a component that is the sole flex/grid item in
   the container being measured. It does **not** fit a component sitting beside a fixed-width sibling
@@ -3721,6 +4473,17 @@ the fullscreen backdrop scrim color), `--lr-widget-fullscreen-inset` (default pe
 tokens (`--lr-space-*`, `--lr-color-border/-surface/-text-quiet`,
 `--lr-radius`, `--lr-shadow`, `--lr-icon-button-size`, `--lr-focus-ring-*`).
 
+Two further properties style the pressed view toggle: `--lr-widget-view-toggle-active-bg` (default
+`var(--lr-color-brand-quiet)`) and `--lr-widget-view-toggle-active-color` (default
+`var(--lr-color-brand)`) — the background and text color of the `aria-pressed="true"` toggle. Both
+are **state hooks**: declared as inline `var()` fallbacks at the point of use and never on `:host`,
+so setting either on the element *or on any ancestor* reaches the toggle. That shape exists because
+`::part(view-toggle)[aria-pressed='true']` is not valid CSS — Shadow Parts forbids an attribute
+selector after `::part()` — so before these hooks the only way to recolor an active toggle was to
+override the library-wide `--lr-color-brand-quiet`/`--lr-color-brand` tokens, repainting every other
+element that reads them. Left unset, each falls back to exactly the token the rule used before, so
+rendering is unchanged.
+
 **Optional peer deps:** none.
 
 ```html
@@ -3775,6 +4538,15 @@ viewport), `track`, `controls`, `previous-button`, `next-button`, `previous-glyp
 chevron inside each, mirrored under RTL), `indicators`, `indicator` (one indicator's hit target,
 sized to the shared minimum tappable size), and `indicator-dot` (the compact visible dot inside it).
 
+**Themeable custom properties:** `--lr-carousel-indicator-current-bg` (default
+`var(--lr-color-brand-quiet)`) and `--lr-carousel-indicator-current-border-color` (default
+`var(--lr-color-brand)`) — background and border color of the current slide's `indicator-dot`
+(`[aria-current='true']`). Same state-hook mechanics as `<lr-widget>`'s view-toggle pair above:
+inline `var()` fallbacks, never declared on `:host`, so either can be set on the element or on any
+ancestor; unset, each falls back to the token the rule used before. This shape is what makes the
+current indicator addressable at all — `::part(indicator)[aria-current='true']` is invalid CSS, so
+hijacking a library-wide color token was previously the only lever.
+
 ```html
 <lr-carousel aria-label="Screenshots">
   <img alt="Dashboard overview" src="overview.png">
@@ -3896,7 +4668,18 @@ inside a tab button; only rendered when that tab has a matching `<id>-icon` sibl
 single `role="tabpanel"` wrapper, one per tab, hidden unless active)
 
 **Themeable custom properties:** `--lr-scroll-fade-size` (default `2rem`) — width of the static
-mask fade at each horizontal scroll edge of the tablist. Otherwise shared tokens —
+mask fade at each horizontal scroll edge of the tablist. `--lr-tabs-selected-color` (default
+`var(--lr-color-brand)`) — text color of the selected tab, scoped to `[aria-selected='true']` only,
+so it never repaints a hovered unselected tab. `--lr-tabs-indicator-color` (default
+`var(--lr-color-brand)`) — the selected tab's underline, themeable independently of its text color.
+`--lr-tabs-hover-color` (default `var(--lr-color-text)`) — text color of a hovered, non-disabled
+tab, independent of the two selected-state hooks. All three are declared as inline `var()` fallbacks
+at the point of use rather than on `:host`, so each can be set on the element *or on any ancestor* —
+the pattern exists because `::part(tab)[aria-selected='true']` is invalid CSS (Shadow Parts forbids
+an attribute selector after `::part()`), which previously left overriding the library-wide
+`--lr-color-brand`/`--lr-color-text` tokens as the only way to restyle a selected or hovered tab,
+repainting everything else that reads them. Unset, each falls back to the token its rule used
+before, so rendering is unchanged. Otherwise shared tokens —
 `--lr-space-xs/-s/-m`, `--lr-color-border/-text-quiet/-text/-brand`, `--lr-transition-fast`,
 `--lr-radius`, `--lr-focus-ring-width/-color/-offset`, `--lr-opacity-disabled`.
 
@@ -3937,10 +4720,13 @@ convention).
 
 **Properties:**
 - `steps: StepItem[] = []` (attribute: false) — `StepItem { id: string; label: string; state:
-  'pending' | 'current' | 'completed' | 'disabled' | 'error'; title?: string }`; `title` is an
-  optional native tooltip for the step's button (e.g. explaining why a `disabled` step is locked) —
-  omit it for no `title` attribute at all, not an empty string. Never mutated by this component.
-  Empty (the default) renders nothing.
+  'pending' | 'current' | 'completed' | 'disabled' | 'error'; title?: string; icon?: unknown }`;
+  `title` is an optional native tooltip for the step's button (e.g. explaining why a `disabled` step
+  is locked) — omit it for no `title` attribute at all, not an empty string. `icon` is an optional
+  leading topic glyph (a `TemplateResult`, an emoji string, etc. — not restricted to a square icon)
+  rendered in the `step-icon` part additionally to, never instead of, the state-driven
+  `step-index`/`step-check` glyph. Never mutated by this component. Empty (the default) renders
+  nothing.
 - `orientation: 'horizontal' | 'vertical' = 'horizontal'` (reflected) — `'horizontal'` (the default)
   lays steps out in a row (Left/Right, RTL-aware, navigate); `'vertical'` stacks them (Up/Down
   navigate instead, no RTL swap needed). The axis used at/above `orientationBreakpoint` (or always,
@@ -3989,11 +4775,25 @@ single place to short-circuit its own listener's follow-up work. `lr-stepper-ori
 **Slots:** none.
 
 **CSS parts:** `base` (root wrapper, `role="tablist"`), `step` (a single step button, `role="tab"`),
-`step-index` (the numbered index chip, shown for `pending`/`current`/`error` steps), `step-check`
-(the completed-checkmark glyph, shown for `completed` steps instead of `step-index`), `step-label`
-(the step's label text).
-
-**Themeable custom properties:** shared tokens only — `--lr-space-m`/`-xs`/`-2xs`,
+`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
+glyph, shown for `completed` steps instead of `step-index`), `step-label` (the step's label text).
+
+**Themeable custom properties:** `--lr-stepper-current-color` (default `var(--lr-color-text)`) —
+text color of the `current` step. `--lr-stepper-current-font-weight` (default
+`var(--lr-font-weight-semibold)`) — font weight of the `current` step's label.
+`--lr-stepper-error-color` (default `var(--lr-color-danger)`) —
+text color of an `error` step. `--lr-stepper-current-index-bg` (default `var(--lr-color-brand)`) and
+`--lr-stepper-current-index-color` (default `var(--lr-color-surface)`) — background and text color
+of the `current` step's numbered `step-index` chip. Each is an inline `var()` fallback at the point
+of use, never declared on `:host`, so it can be set on the element or on any ancestor; and each is
+scoped to its own `data-state`, so recoloring the current step leaves `pending`/`completed`/`error`
+steps alone. The hooks exist because `::part(step)[data-state='current']` is invalid CSS — Shadow
+Parts forbids an attribute selector after `::part()` — so state-specific theming previously meant
+overriding a library-wide `--lr-color-*` token and repainting everything else that read it. Unset,
+each falls back to the token its rule used before. Otherwise shared tokens —
+`--lr-space-m`/`-xs`/`-2xs`,
 `--lr-color-text-quiet`/`-text`/`-danger`/`-brand`/`-surface`, `--lr-radius`/`-pill`,
 `--lr-font-size-xs`, `--lr-font-weight-semibold`, `--lr-opacity-disabled`,
 `--lr-focus-ring-*`.
@@ -4100,7 +4900,29 @@ fade at each horizontal scroll edge of the track. `--lr-segmented-track-min-heig
 `--lr-segmented-segment-padding`, and `--lr-segmented-font-size` are the three knobs `size` swaps
 (`m` defaults: `auto`, `var(--lr-size-0-125rem) var(--lr-space-s)`, `var(--lr-font-size-sm)`) —
 override them on the host for a size tier the scale doesn't cover, since a `:host([size])` rule
-wins over the `:host` default. Otherwise shared tokens — `--lr-color-border`/`-surface`/`-text`/
+wins over the `:host` default.
+
+`--lr-segmented-track-height` pins the `base` track's exact height at every `size` tier (it sets
+both `block-size` and `min-block-size`), for a row that has to sit flush beside a hard-sized toolbar
+control. It is **genuinely undeclared by default** — not `auto` — and that is load-bearing: an
+exact-height hatch only works as an undeclared sentinel, because `auto` is itself a valid value that
+would always win and would silently turn every tier's `--lr-segmented-track-min-height` floor into
+dead code. While it is unset, each tier keeps its own floor and the track grows with its content.
+
+`--lr-segmented-selected-bg` (default `var(--lr-color-surface)`), `--lr-segmented-selected-color`
+(default `var(--lr-color-text)`), `--lr-segmented-selected-font-weight` (default
+`var(--lr-font-weight-semibold)`) and `--lr-segmented-selected-shadow` (default `var(--lr-shadow)`)
+style the checked segment's pill; `--lr-segmented-hover-color` (default `var(--lr-color-text)`)
+styles a hovered segment that is neither checked nor disabled, independently of the four above — so
+recoloring the checked pill never bleeds onto hover. All five are inline `var()` fallbacks at the
+point of use rather than `:host` declarations, so each can be set on the element *or on any
+ancestor*; unset, each falls back to the token its rule used before. They exist because
+`::part(segment)[aria-checked='true']` is invalid CSS — Shadow Parts forbids an attribute selector
+after `::part()` — which previously left hijacking the library-wide
+`--lr-color-surface`/`--lr-color-text` tokens as the only way to restyle a selected segment,
+repainting every other element that read them.
+
+Otherwise shared tokens — `--lr-color-border`/`-surface`/`-text`/
 `-text-quiet`, `--lr-radius`, `--lr-font-weight-semibold`, `--lr-space-s`, `--lr-shadow`,
 `--lr-opacity-disabled`, `--lr-focus-ring-*`.
 
@@ -4150,10 +4972,39 @@ invention (no Web Awesome equivalent).
   which is only a safe identity while `items` never reorders/inserts/removes — provide this whenever
   possible, or scroll position and per-row DOM state (e.g. an `<audio>` element's playback position)
   can attach to the wrong row across a mutation.
-- `groups?: VirtualListGroup[]` (attribute: false) — renders a labeled `role="heading"` marker at each
-  group's `startIndex`, positioned independently of the row window (so it stays in place as its rows
-  scroll past). Groups are sorted by `startIndex`; a `startIndex` that's non-integer, out of range, or
-  a duplicate of an earlier group's is silently dropped rather than rendered wrong.
+- `groups?: VirtualListGroup[]` (attribute: false) — renders a labeled marker at each group's
+  `startIndex`, positioned independently of the row window (so it stays in place as its rows scroll
+  past). Groups are sorted by `startIndex`; a `startIndex` that's non-integer, out of range, or a
+  duplicate of an earlier group's is silently dropped rather than rendered wrong. An entry whose
+  `label` is the **empty string** renders no marker at all — it is a pure position anchor, for a host
+  that renders its own group header as an ordinary row (and would otherwise end up with two stacked
+  headers) but still needs this component to know where each group starts, e.g. to drive
+  `renderStickyGroup` below. Omitting `label` entirely still falls back to rendering `key`.
+- `renderStickyGroup?: (group: VirtualListGroup) => unknown` (attribute: false) — renders a pinned
+  copy of whichever `groups` entry the viewport is currently inside, into a `[part="sticky-group"]`
+  overlay that stays at the top of the scroll viewport and is pushed out by the overlap as the next
+  group's header arrives (rather than swapped abruptly at the boundary). Native `position: sticky` on
+  the rows or markers themselves cannot do this: every row is absolutely positioned and
+  transform-offset by the windowing math, which makes sticky structurally inert. Unset (the default)
+  renders no overlay element whatsoever and changes nothing about the list's output. The overlay is a
+  *visual copy* of content that already exists in the list, which fixes its contract:
+  - it is `aria-hidden`, and ordinary focusable HTML inside it is forced to `tabindex="-1"`, so the
+    real row keeps sole ownership of the heading semantics and of the tab order (a focus-delegating
+    custom element rendered into the copy needs its own `tabindex="-1"`; `inert` is deliberately not
+    used, because it would also block the pointer opt-in below);
+  - it is `pointer-events: none` by default — opt back in with
+    `lr-virtual-list::part(sticky-group) { pointer-events: auto; }` when the copied header content is
+    interactive;
+  - it is never measured as a row, so a group header that is also a real row is not double-counted in
+    `row-height="auto"` mode;
+  - its measured height is applied as `scroll-padding-block-start` on the scroll container and
+    subtracted from top-aligned scroll targets, so `active-id`, `scrollToIndex({ align: 'start' })`
+    and native keyboard scrolling all stop *below* the band instead of parking the row behind it.
+
+  The callback runs on every scroll-driven update, so keep it cheap and side-effect free. While the
+  viewport is above the first group there is nothing to pin: the band shows nothing, but it stays
+  mounted (called with the first group, rendered hidden) so its height is known before the first
+  programmatic jump rather than only after it.
 - `rowHeight: string = 'auto'` (attribute `row-height`) — `'auto'` measures each row's real height via
   `ResizeObserver`; a numeric string (e.g. `"56"`) fixes every row to that many pixels. Anything else
   (non-numeric, zero, negative, non-finite) silently falls back to `'auto'` rather than throwing.
@@ -4180,7 +5031,8 @@ invention (no Web Awesome equivalent).
 
 **Exported types:** `VirtualListRange { start: number; end: number }` (the `lr-visible-range-changed`
 detail shape); `VirtualListGroup { key: string | number; label?: string; startIndex: number }` — the
-shape consumed by `groups` above.
+shape consumed by `groups` above; `VirtualListScroll { scrollTop: number; viewportHeight: number }` —
+the `lr-scroll` detail shape.
 The package root also exports `groupByRecency(items, options?)`, a DOM-free helper that returns
 non-empty Today/Yesterday/Previous 7 Days/Older buckets, preserves input order within each bucket,
 and accepts a timestamp extractor, reference date, and label overrides.
@@ -4190,12 +5042,35 @@ automatic scroll-into-view, for a host that needs to scroll to a specific row wi
 row is "active." `options.align` is `'start'`, `'end'`, or `'auto'` (default — no scroll at all when
 already fully visible); `options.behavior` (default `'smooth'`) is forced to `'auto'` under
 `prefers-reduced-motion: reduce`. `index` is clamped to `0…items.length-1`.
+`offsetForIndex(index)` returns the pixel top row `index` renders at, in the same coordinate space as
+the scroll container's `scrollTop`; it is clamped to `0…items.length`, so `offsetForIndex(items.length)`
+is the total content height and an empty list is always `0`. `indexAtOffset(px)` is its inverse — the
+row whose box contains that offset, clamped at both ends, `-1` for an empty list — so
+`indexAtOffset(offsetForIndex(i)) === i` and `indexAtOffset(scrollContainer.scrollTop)` is the row at
+the top of the viewport. In `row-height="auto"` mode both are estimate-based for any row that (or
+above which) has not been measured yet, and converge as those `ResizeObserver` measurements land;
+fixed numeric `row-height` offsets are exact from the first render. Both read the most recent render,
+so `await el.updateComplete` after assigning `items` before querying.
+
+**Getters:** `scrollContainer: HTMLElement | undefined` — the real scroll container (`[part="base"]`),
+`undefined` before the first render; for a host that needs the live scroll position or wants to scroll
+the list itself without reaching into the shadow root. `renderedRows: HTMLElement[]` — the row
+wrappers (`[part="row"]`) that currently exist as real DOM, in item order (the current window, not the
+whole collection; empty before the first render). It exists for hosts that must *reach* a rendered row
+rather than style it — keyboard focus management across a windowed list, where the row to focus may
+not have existed a frame earlier, and which `exportparts` cannot serve since it forwards styling, not
+element references. Treat both as read-only: positioning, keys, and lifetime belong to the windowing
+math, and any row element can be recycled or removed on the next update.
 
 **Events:** `lr-load-more` (no detail — fired once per approach to the bottom of the list while
 `has-more` is true and `loading` is false; does not refire on every scroll tick while still near the
 bottom — scrolling back away from the bottom and returning, or `items` growing enough to move the
 window away from the end, re-arms it), `lr-visible-range-changed` (`detail: VirtualListRange`, the
-current visible, non-overscanned item index range — fired only when it actually changes)
+current visible, non-overscanned item index range — fired only when it actually changes), `lr-scroll`
+(`detail: VirtualListScroll` — the scroll container moved; emitted from the same animation frame that
+already coalesces native `scroll` events, so a fling produces at most one per frame and none at all
+when the position did not change. Unlike `lr-visible-range-changed`, which only fires on index-range
+changes, this reports *sub-row* movement, which is what scroll-linked layout needs)
 
 **Slots:** none — all content comes from `renderItem`.
 
@@ -4203,8 +5078,11 @@ current visible, non-overscanned item index range — fired only when it actuall
 `item-role="row"` mode — `tabindex="0"`), `spacer` (the full-content-height inner element
 establishing true scroll extent; `role="presentation"` in `item-role="row"` mode), `row` (one
 rendered row's absolutely-positioned wrapper, `role="listitem"` — or `role="row"` with
-`aria-rowindex` in `item-role="row"` mode), `group` (a `groups` entry's positioned `role="heading"`
-marker)
+`aria-rowindex` in `item-role="row"` mode), `group` (a `groups` entry's positioned marker; not
+rendered for an entry whose `label` is the empty string), `sticky-group` (the pinned copy of the
+current group, present only while `renderStickyGroup` is set — `aria-hidden` and
+`pointer-events: none` by default; style it with `pointer-events: auto` to make copied interactive
+content clickable, and it shows nothing while the viewport is above the first group)
 
 **Themeable custom properties:** `--lr-virtual-list-height` (default `24rem` — the host's bounded
 scroll extent; component-specific since a virtualized list is meaningless without a sized viewport),
@@ -4233,6 +5111,20 @@ so it isn't clipped by the container's own `overflow: auto`).
 ></lr-virtual-list>
 ```
 
+```html
+<!-- Sticky group headers: the header is a real row, so the `groups` entries are position anchors
+     only (`label: ''`), and the pinned copy opts back into pointer events for its own toggle. -->
+<lr-virtual-list
+  .items=${rows}
+  .groups=${groupStarts /* [{ key: 'Today', label: '', startIndex: 0 }, …] */}
+  .renderItem=${(item, index) => (item.isHeader ? headerTemplate(item) : rowTemplate(item))}
+  .renderStickyGroup=${(group) => headerTemplate(group)}
+></lr-virtual-list>
+<style>
+  lr-virtual-list::part(sticky-group) { pointer-events: auto; }
+</style>
+```
+
 Every row — in both `row-height` modes — is positioned by a `transform: translateY(offset)` computed
 from a single cumulative offsets array, rather than by page flow; this is what lets a small DOM window
 exist while the scrollbar still reflects the true total content height. That array is rebuilt only
@@ -4260,8 +5152,27 @@ history sidebar); it is not the right approach for a hundred-thousand-row list w
 - `aria-setsize`/`aria-posinset` are computed from a row's real index in the full `items` array, not its
   position among the currently-rendered DOM window, so assistive tech still announces e.g. "item 12 of
   340" correctly even though only a handful of rows exist in the DOM at a time.
-- `groups` is accepted today purely for forward API compatibility; setting it has no visible effect
-  yet.
+- `groups`, `renderStickyGroup`, `offsetForIndex()`/`indexAtOffset()` and the `lr-scroll` event are
+  all expressed against the *same* windowing math, so they agree with each other — but that math is
+  estimate-based in `row-height="auto"` mode until the rows involved have been measured. Read a
+  position after `await el.updateComplete`, and expect the value to converge rather than be final on
+  the first frame.
+- A sticky band only appears when `renderStickyGroup` *and* at least one valid `groups` entry are
+  both present; `groups` alone renders positioned markers with nothing pinned, and
+  `renderStickyGroup` alone renders no overlay element at all.
+- **A row that renders a popup needs the focused-row lift, and this is why `[part='row']` has one.**
+  Each row carries `will-change: transform` (a compositor hint for the per-frame translate), which
+  makes every row its own stacking context. Rows otherwise carry no `z-index`, so they paint in DOM
+  order and each one paints over the previous. Anything a row renders that overflows its own box —
+  an `<lr-menu>` popup in a row-action menu, a tooltip, an outward focus ring — is therefore painted
+  *underneath* every following row, no matter how high its own `z-index` is: that `z-index` only
+  orders siblings inside the row's own context. The last row always looks correct, which is exactly
+  why a short fixture never catches it. `[part='row']:focus-within` lifts the row to
+  `--lr-layer-content` for precisely as long as something inside it holds focus — the lifetime of an
+  open popup — and costs nothing otherwise. The value deliberately *matches* `[part='group']`'s
+  rather than exceeding it, so the two land on the same layer and DOM order decides: groups render
+  before the rows, so a focused row wins while (and only while) it holds focus, which is right — a
+  group header is a non-interactive `pointer-events: none` label.
 
 ---
 
@@ -4467,6 +5378,17 @@ when the item has an explicit `aria-label`).
 **CSS parts:** `base`, `icon`, `label`, `tooltip` (the hover/focus label flyout, only rendered while
 `tooltip` is set, the item is `icon-only`, and it is hovered or focused).
 
+**Themeable custom properties:** `--lr-app-rail-item-current-bg` (default
+`var(--lr-color-brand-quiet)`) and `--lr-app-rail-item-current-color` (default
+`var(--lr-color-brand)`) — background and text/icon color of the `active` (`aria-current="page"`)
+item. Both are scoped to `[aria-current='page']` only and declared as inline `var()` fallbacks at
+the point of use, never on `:host`, so either can be set on the item itself *or on any ancestor* —
+including on `<lr-app-rail>` or a wrapper above it, to tint every item's active state at once.
+`::part(base)[aria-current='page']` is invalid CSS (Shadow Parts forbids an attribute selector after
+`::part()`), so before these hooks the only lever was overriding the library-wide
+`--lr-color-brand-quiet`/`--lr-color-brand` tokens, which repainted every other element reading
+them. Unset, each falls back to the token its rule used before.
+
 **Optional peer deps:** none.
 
 ---
@@ -4520,7 +5442,11 @@ the *effective* mode — not the `mode` prop's possibly-`'auto'` literal value
 in the overlay presentation).
 
 **Themeable custom properties:** `--lr-responsive-panel-overlay-color` (default
-`var(--lr-color-overlay)` — the overlay presentation's backdrop scrim color), plus shared tokens (`--lr-color-border`, `--lr-color-surface`,
+`var(--lr-color-overlay)` — the overlay presentation's backdrop scrim color),
+`--lr-responsive-panel-sheet-max-block-size` (default `85dvh`, falling back to `85vh` where `dvh`
+isn't supported — the maximum height of a `variant="bottom-sheet"` overlay panel, so a long sheet
+stops short of the top of the viewport instead of covering it; it has no effect on
+`variant="fullscreen"` or on the inline presentation), plus shared tokens (`--lr-color-border`, `--lr-color-surface`,
 `--lr-space-*`, `--lr-radius`, `--lr-shadow`).
 
 **Optional peer deps:** none.
@@ -4597,8 +5523,25 @@ menu, an avatar menu, or a history row's overflow menu. Uses the WAI-ARIA "menu
   `this.getAttribute('aria-label') || <computed default>` precedence
 
 - `closeOnEscapeAnywhere: boolean = false` (attribute `close-on-escape-anywhere`) — lets Escape
-  close the menu when focus is on slotted non-menu-item content inside the popup; item activation
-  remains scoped to actual menu items
+  close the menu when focus is on non-menu-item content slotted into the **default** slot, i.e.
+  rendered inside `[part="list"]`; item activation remains scoped to actual menu items. It has no
+  bearing on the `header`/`footer` slots, which sit outside the `role="menu"` list and always close
+  on Escape — so a menu that keeps its composed controls there never needs this property
+
+**Methods:** `show(focus: 'first' | 'last' = 'first')` opens the menu and moves roving focus to the
+first (or, with `'last'`, the last) non-disabled item; a no-op when already open.
+`hide(options?: { focusTrigger?: boolean })` closes it; a no-op when already closed. They are the
+imperative pair for the cases the slotted trigger can't express — a "Done"/"Apply" button *inside*
+the menu, a keyboard shortcut, a parent restoring UI state — without hand-reproducing the
+pending-focus bookkeeping. Both are deliberately thin: positioning, the outside-click listener, the
+`lr-show`/`lr-hide` events, and the initial focus move all stay in one place, so **writing `open`
+directly is fully supported and equivalent apart from the focus moves**. In particular the
+roving-tabindex reset is centralized, so a bare `el.open = false` also clears `activeIndex` and
+never leaves a stale `tabindex="0"` tab stop on the last active item. `hide()` never refocuses
+unless you ask: pass `{ focusTrigger: true }` for a dismissal with nowhere else for focus to land,
+and leave it off when the interaction that closed the menu already put focus somewhere the user
+chose (an outside click, a Tab out). Focus restoration lives in `hide()` rather than in the
+close branch precisely so teardown — disconnecting an open menu — can't steal focus.
 
 **Events:** `lr-show` (no detail — fires only when `open` transitions to `true`, not for markup
 that renders `open` true from the start), `lr-hide` (same first-render guard, opposite
@@ -4610,10 +5553,25 @@ returning to the trigger)
 are assigned; enhanced imperatively with `aria-haspopup="menu"`/`aria-expanded`/`aria-controls`
 since those attributes belong on the actual interactive trigger, which lives outside this
 component's shadow root), default (`<lr-menu-item>` elements, plus optionally plain `<hr>`
-dividers between groups — native `<hr>` already carries an implicit `separator` role)
+dividers between groups — native `<hr>` already carries an implicit `separator` role),
+`header` and `footer` (composed, deliberately non-menu-item content — a filter/search field, a
+section title, an "Apply"/"Done" button, a count — rendered above/below the items inside
+`[part="popup"]` but **outside** the `role="menu"` list. Both collapse to no box at all while
+unfilled, so a menu that uses neither renders exactly as it did before they existed)
+
+Put composed controls in `header`/`footer` rather than the default slot. Non-item content in the
+default slot still works and is not deprecated at runtime (no warning is emitted), but it sits
+inside `role="menu"`, where ARIA permits only
+`menuitem`/`menuitemradio`/`menuitemcheckbox`/`group`/`separator` children — anything else is an
+`aria-required-children` violation. It is also not Tab-reachable from an item, and needs
+`closeOnEscapeAnywhere` before Escape will close the menu. The named regions have none of those
+problems.
 
 **CSS parts:** `trigger` (wrapper around the `trigger` slot — the positioning anchor), `popup` (the
-positioned floating panel), `list` (the `role="menu"` container wrapping the default slot)
+positioned floating panel), `header` (wrapper around the `header` slot, above the list and outside
+`role="menu"`; `display: none` while that slot is unfilled), `list` (the `role="menu"` container
+wrapping the default slot), `footer` (wrapper around the `footer` slot, below the list and outside
+`role="menu"`; `display: none` while that slot is unfilled)
 
 **Themeable custom properties:** shared tokens only (`--lr-color-surface`, `--lr-color-border`,
 `--lr-radius`, `--lr-shadow`, `--lr-space-xs`, `--lr-transition-fast`).
@@ -4703,11 +5661,19 @@ navigation with no separate JS bookkeeping. ArrowDown/ArrowUp *on the trigger wh
 opens the menu, focusing the first/last non-disabled item respectively (mirrors native `<select>`).
 Once open, ArrowDown/ArrowUp move the roving focus among non-disabled items and wrap past either end
 (unlike `<lr-select>`'s clamped listbox nav); Home/End jump to the first/last non-disabled item;
-Enter/Space activate the focused item; Escape closes and refocuses the trigger; Tab closes without
-`preventDefault()`, letting the browser's own Tab navigation proceed untouched. All of this list-level
-keydown handling — Escape, Tab, the arrow keys, Home/End, and type-ahead alike — only responds when
-the triggering keydown event's own target is an actual `<lr-menu-item>` element; a keydown bubbling
-up from any other node inside the popup is ignored rather than misread as list navigation. A printable
+Enter/Space activate the focused item; Escape closes and refocuses the trigger. The arrow keys,
+Home/End, Enter/Space and type-ahead only respond when the triggering keydown event's own target is
+an actual `<lr-menu-item>` element; a keydown bubbling up from any other node inside the popup is
+ignored rather than misread as list navigation. Escape and Tab are the two deliberate exceptions.
+Escape from `header`/`footer` content always closes the menu and refocuses the trigger (mirroring
+`lr-popover`'s handling of arbitrary popup content), while Escape from non-item content in the
+*default* slot closes it only with `closeOnEscapeAnywhere` set. Tab never traps focus and never
+calls `preventDefault()` — the browser's own Tab navigation always proceeds untouched — and closes
+the menu only when focus is on its way *out* of `[part="popup"]`: with a focusable in the
+`header`/`footer` region on the far side of the keypress the menu stays open so native Tab can carry
+focus there, and with neither region filled Tab closes exactly as it always has. Tabbing past the
+popup's last focusable in either direction closes the menu, including from slotted non-item content
+— which previously left the menu open while focus walked out of the popup entirely. A printable
 keypress runs type-ahead: roving focus jumps to the next non-disabled item whose text starts with the
 accumulated buffer (cycling from just after the active item, buffer resets ~500ms after the last
 keystroke) — mirrors `<lr-select>`'s identical listbox type-ahead. A click outside both the trigger
@@ -4725,8 +5691,20 @@ click itself already moved focus somewhere the user chose.
 - `lr-menu-item-select` carries no detail payload (`event.detail === null`); read
   `event.target.value` instead. `<lr-menu>`'s own re-fired `lr-menu-select` is the one that
   carries `detail: { value }`.
-- Tab closes the menu without `preventDefault()` or focus trapping — the browser's own default Tab
-  navigation proceeds untouched, only the (now-stale) open state is cleared.
+- Tab never calls `preventDefault()` and never traps focus — the browser's own default Tab
+  navigation always proceeds untouched. It closes the menu only when Tab would leave
+  `[part="popup"]` entirely; when the `header`/`footer` region holds a focusable on the far side of
+  the keypress, the menu stays open instead and native Tab moves focus into it. With neither region
+  filled, Tab closes exactly as before.
+- Non-item content in the *default* slot is not Tab-reachable from an item — Tab from an
+  `<lr-menu-item>` still closes the menu when there is no `header`/`footer` focusable to move to,
+  even if a `<button>` is slotted alongside the items. Move such controls to `header`/`footer`.
+- `header`/`footer` emptiness is tracked from each slot's own `slotchange` and reflected on the host
+  as `data-has-header` / `data-has-footer` (plus `data-list-empty`, which suppresses the region
+  divider next to an empty list). They are internal styling hooks, not public API — don't set them
+  by hand — but they are why `[part="header"]`/`[part="footer"]` collapse cleanly: a
+  `[part]:empty` rule can never match a part that contains a slot, since Chromium counts the
+  whitespace-only text nodes Lit leaves there.
 - Only Escape and a committed selection refocus the trigger on close; a click outside does not.
 
 ---
@@ -4842,14 +5820,19 @@ to `<wa-card>`'s contract, staying slot-compatible with `lr-result-card` where t
   for a quiet brand-tinted background; `'filled-outlined'` keeps the border and adds that same tinted
   background; `'accent'` drops the border for a single colored accent stripe on the leading edge;
   `'plain'` has no border or background at all.
-- `interactive: boolean = false` (reflected) — opt-in hover/focus-visible treatment (border-color
-  shift, cursor: pointer) for a card used as a clickable tile — purely visual; this component takes
-  no position on what "activate" means unless `href` is also set. `false` (the default) reproduces a
-  plain static card.
+- `interactive: boolean = false` (reflected) — opt-in clickable-tile behavior: the hover/focus-visible
+  treatment (border-color shift, `cursor: pointer`) plus, when `href` is **not** also set, real
+  activation semantics — `[part='base']` becomes focusable (`tabindex="0"`), responds to
+  Enter/Space, and emits `lr-card-activate`. With `href` set, the root is already a real `<a>`, so
+  native navigation *is* the activation and `lr-card-activate` never fires. `false` (the default)
+  reproduces a plain static card: no `tabindex`, no listeners, no events.
 - `href?: string` — when set, the card's root renders as a real `<a href=...>` instead of a `<div>`,
   for a whole-card link (e.g. a wide CTA tile). Unset (the default) renders a plain `<div>`.
 
-**Events:** none.
+**Events:** `lr-card-activate` (no detail) — the whole card was activated, by click or by
+Enter/Space while `[part='base']` has focus. Only fired while `interactive` is set **without**
+`href`. Never fired for an interaction that originated in a slotted control, so a card can keep its
+own action buttons (see the gotchas below).
 
 **Slots:** default (the card body), `header` (header row content, rendered above the body), `media`
 (media content, e.g. an image, rendered above the header), `footer` (footer content, rendered below
@@ -4883,6 +5866,22 @@ the `footer` slot, hidden entirely when empty).
 - slot-presence (`header`/`media`/`footer`/`actions`) is tracked in JS, not via CSS `:empty` (a
   `[part]` wrapper always contains a literal `<slot>` child, so `:empty` never matches) — the same
   pattern `lr-empty`/`lr-widget` use.
+- **an `interactive` card without `href` deliberately carries no `role="button"`.** A card is a
+  *container* — it routinely holds slotted buttons and links — and `role="button"` around focusable
+  descendants is the `nested-interactive` accessibility violation this library's own a11y gate
+  enforces. (`lr-chip`'s `toggleable` mode *can* carry `role="button"` because it forbids focusable
+  children outright.) The consequence is that the card is announced as a plain focusable region, so
+  give it your own `aria-label` when the content doesn't already name it.
+- because there is no `role="button"` to disambiguate, "did the user aim at the card or at a control
+  inside it?" is answered at event time: the composed path from the original target up to
+  `[part='base']` is walked, and `lr-card-activate` is suppressed if anything along the way is
+  itself a control (a link, `button`, `input`, `select`, `textarea`, `label`, `summary`,
+  `contenteditable`, anything carrying a `tabindex` other than `-1`, or an ARIA widget role such as
+  `button`/`link`/`checkbox`/`switch`/`radio`/`menuitem`/`option`/`tab`/`textbox`/`slider`/
+  `spinbutton`). Using the *composed*
+  path is what makes this work through a slotted component's own shadow root — a click on
+  `<lr-button>` retargets to the host, but its composed path still contains the internal native
+  `<button>`.
 
 ---
 
@@ -4895,10 +5894,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
@@ -4917,13 +5919,21 @@ 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.
 
 ## `lr-details`, `lr-accordion`, and `lr-accordion-item`
 
@@ -4954,6 +5964,15 @@ its label.
 **CSS parts:** breadcrumb `base` (the `<nav>`) and `list` (the `role="list"` flex row wrapping the
 slotted items); item `base` (the `<a>` or `<span>`).
 
+**Themeable custom properties:** `--lr-breadcrumb-current-color` (default
+`var(--lr-color-text-quiet)`) — text color of the current-page item (`current`/`aria-current="page"`).
+It is an inline `var()` fallback at the point of use rather than a `:host` declaration, so it can be
+set on the item, on `<lr-breadcrumb>`, or on any ancestor above the trail:
+`::part(base)[aria-current='page']` is invalid CSS (Shadow Parts forbids an attribute selector after
+`::part()`), so tinting the current item previously meant overriding the library-wide
+`--lr-color-text-quiet` token and repainting everything else that read it. Unset, it falls back to
+that token.
+
 ## `lr-dashboard-grid`
 
 Responsive, keyboard-accessible controlled widget grid. It positions layout entries and emits
@@ -5000,6 +6019,29 @@ Dashboard filter row that composes Lyra inputs and removable chips, with reset a
 `lr-validity-change`. **CSS parts:** `base`, `controls`, `filter-control`, `active-filters`,
 `chips`, `chip`, `reset-button`, `status`.
 
+Each filter definition's `type` selects which existing Lyra input renders it — this component
+composes them and never invents a control of its own. `'select'`/`'combobox'` map to their
+same-named counterparts (with `combobox`'s `multiple` opting into a multi-value filter),
+`'date'`/`'date-range'` both map to `<lr-date-input>` (single vs. `mode="range"`), and `'text'` maps
+to `<lr-input>` for an open-ended free-text query rather than a closed choice set. A `'text'`
+filter's value is the raw query string, verbatim, and its chip shows exactly that string — the same
+text the user typed, not a truncated or normalized form.
+
+A `'text'` filter is the one control that is **not** a fully controlled `.value=` binding.
+Re-rendering a text field from `value` mid-typing would push a stale value back in and drop the
+caret to the end, so the field owns its own value while the user types, and an external `value`
+write is synced back into it only once no edit is in flight (a host write, a chip removal, and
+`reset()` all take that path).
+
+`'text'` filters also accept an optional per-filter `debounce` (ms) — how long to wait after the
+last keystroke before committing the typed value to `value` and emitting a single `lr-input`, so a
+server-side query runs once per pause instead of once per character. Omitted, `0`, or a non-finite
+value means no debounce at all: every keystroke commits immediately. A pending debounce is always
+**flushed** by the field's own `change`/blur, so a blur never loses the last keystroke, and
+**cancelled outright** by `reset()`, by removing that filter's chip, and on disconnect — a stale
+keystroke can never overwrite a reset or fire after teardown. `debounce` is ignored for every other
+`type`, whose commits are discrete choices with nothing to debounce.
+
 # Overlays, status & feedback (`components/overlays/`)
 
 ## `lr-toast` / `lr-toast-item` / `toast()`
@@ -5134,8 +6176,11 @@ attribute), `description` (rich description content, overrides the `description`
 
 **Themeable custom properties:** `--lr-empty-compact-align` (compact mode only; defaults preserve
 the existing `flex-start` cross-axis and `start` text alignment, and `center` centers both),
-`--lr-empty-compact-padding` (default `--lr-space-xs` — padding used in compact mode), plus
-shared tokens (`--lr-space-xs/-s/-l`, `--lr-color-text-quiet/-border/-text`).
+`--lr-empty-compact-padding` (default `--lr-space-xs` — padding used in compact mode),
+`--lr-empty-compact-gap` (default `--lr-space-2xs` — gap between the icon, heading, and description
+in compact mode; the non-compact layout's gap stays the plain shared `--lr-space-s` token, not
+independently themeable), plus shared tokens (`--lr-space-xs/-s/-l`,
+`--lr-color-text-quiet/-border/-text`).
 
 **Optional peer deps:** none.
 
@@ -5472,12 +6517,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
@@ -5732,7 +6795,10 @@ period, shared with `lr-progress-bar`'s sweep).
 
 ## `lr-badge` and `lr-tag`
 
-Compact status labels. Both expose `variant: 'neutral' | 'brand' | 'success' | 'warning' | 'danger'`.
+Compact status labels. Both expose `variant: 'neutral' | 'brand' | 'success' | 'warning' | 'danger'`
+and `size: '2xs' | 'xs' | 's' | 'm' | 'l' | 'xl' = 'm'` (reflected) — the same visual-density scale
+`<lr-chip>` uses, for typography/padding/minimum block size; `m` preserves the original badge
+dimensions. `lr-tag` inherits `size` unchanged from `lr-badge` rather than redeclaring it.
 The two tags share the same visual contract; `lr-tag` is a semantic alias for migration-friendly
 markup.
 
@@ -5742,6 +6808,10 @@ markup.
 — the trio each `:host([variant])` rule rewrites (`neutral` defaults to
 `--lr-color-surface`/`-text`/`-border`; the other four to the matching `*-quiet` fill with the loud
 color for text and border). Set one directly on the element for a tint outside the five variants.
+`--lr-badge-font-size` (default `var(--lr-font-size-sm)`), `--lr-badge-padding-inline` (default
+`var(--lr-space-s)`), and `--lr-badge-min-height` (default `var(--lr-size-1-25rem)`) — the density
+trio each `:host([size])` rule rewrites to that step's font size, inline padding, and minimum block
+size; the `m` defaults above exactly reproduce the pre-`size` fixed badge treatment.
 
 ## `lr-callout`
 
@@ -5767,7 +6837,12 @@ visible "×" glyph inside it — this is what shrinks under `inline`, so the hit
 **Themeable custom properties:** `--lr-callout-background`, `--lr-callout-color`,
 `--lr-callout-border` — the trio each `:host([variant])` rule rewrites (same
 surface/text/border → `*-quiet`/loud/loud scheme as `lr-badge`). `inline` drops the border,
-background, and panel padding regardless of what these are set to.
+background, and panel padding regardless of what these are set to. `--lr-callout-close-hover-bg`
+(default `var(--lr-color-brand-quiet)`) — the close button's `:hover` background, deliberately
+decoupled from `--lr-callout-background` (which every non-neutral `variant` also retargets for the
+panel itself) so a consumer can retint the hover fill — e.g. to keep it visibly distinct from a
+`variant="brand"` panel, which shares the same default token — without a collateral effect on the
+panel background, and vice versa.
 
 ## `lr-rating`
 
@@ -5820,7 +6895,10 @@ built-in download completes), `lr-show`, `lr-hide` (format-menu visibility trans
 
 **CSS parts:** `trigger`, `menu`, `menu-item`, `format-label`, `format-description`
 
-**Themeable custom properties:** shared tokens only.
+**Themeable custom properties:** shared tokens only, including `--lr-popover-viewport-clamp`
+(default `92vw`) — the shared narrow-viewport ceiling the `menu`'s max-inline-size is `min()`ed
+against, alongside its own `20rem` cap and the positioner's available space. See `lr-tour` for the
+shared-clamp note.
 
 **Optional peer deps:** none.
 
@@ -6011,9 +7089,12 @@ clipboard") or a per-node one (aria-label `Copy ${key/type}`, e.g. "Copy age");
 `copyable`)
 
 **Themeable custom properties:** `--lr-json-viewer-max-height` (default `none` — grows with content
-until `max-height` is set), `--lr-json-viewer-font` (default `ui-monospace, SFMono-Regular, Menlo,
-Consolas, monospace` — component-specific since no shared monospace token exists), plus shared tokens
-`--lr-color-border/-surface/-text/-text-quiet/-brand/-brand-quiet/-success/-warning/-warning-quiet`,
+until `max-height` is set), `--lr-json-viewer-font` (default `var(--lr-font-mono)`),
+`--lr-json-viewer-match-bg` (default `var(--lr-color-warning-quiet)`) — background, and surrounding
+box-shadow, of a key/value that currently matches `search`. Component-scoped indirection over the
+shared `--lr-color-warning-quiet` token, so a consumer can retheme just this search-match highlight
+without repainting every other warning-toned surface that reads the same shared token. Plus shared
+tokens `--lr-color-border/-surface/-text/-text-quiet/-brand/-brand-quiet/-success/-warning/-warning-quiet`,
 `--lr-radius`, `--lr-space-xs/-s/-l`, `--lr-focus-ring-width/-color/-offset`,
 `--lr-transition-fast`.
 
@@ -6166,7 +7247,11 @@ button).
 **CSS parts:** `base`, `indicator` (the pulsing status dot), `countdown` (the `M:SS`, or
 "Refreshing…", text), `pause-button` (the built-in pause/resume toggle).
 
-**Themeable custom properties:** shared tokens only — `--lr-space-xs`, `--lr-font-size-sm`,
+**Themeable custom properties:** `--lr-poll-status-due-bg` (default `var(--lr-color-success)`) —
+background of `indicator` while `data-due` is set. Component-scoped indirection over the shared
+`--lr-color-success` token, so a consumer can retheme just this due-state indicator without
+repainting every other component that reuses the same shared success token. Plus shared tokens —
+`--lr-space-xs`, `--lr-font-size-sm`,
 `--lr-color-text-quiet`, `--lr-color-brand`, `--lr-color-success`, `--lr-radius`/`-pill`,
 `--lr-focus-ring-*`.
 
@@ -6256,12 +7341,19 @@ renders `open="false"` on first paint)
 **CSS parts:** `listbox`, `option`, `option-icon` (when `icon` is set), `option-label`,
 `option-description` (when `description` is set), `empty`
 
-**Themeable custom properties:** shared tokens only — `--lr-space-xs`/`-s`/`-m` (popup padding,
+**Themeable custom properties:** `--lr-mention-popover-option-active-bg` (default
+`var(--lr-color-brand-quiet)`) — background of the hovered or `[data-active]`
+(keyboard-highlighted) suggestion row. Component-scoped indirection over the shared
+`--lr-color-brand-quiet` token, so a consumer can retheme just this highlighted/active row without
+repainting every other component that reuses the same shared token. Plus shared tokens —
+`--lr-space-xs`/`-s`/`-m` (popup padding,
 row padding/gap), `--lr-color-surface`/`-border` (popup background/border), `--lr-radius`
 (popup and row corners), `--lr-shadow` (popup elevation), `--lr-transition-fast` (open/close
-transition), `--lr-color-brand-quiet` (active-row background), `--lr-color-brand` (selected-row
+transition), `--lr-color-brand` (selected-row
 text), `--lr-color-text-quiet`/`--lr-color-text` (description text, full-contrast on the active
-row).
+row), and `--lr-popover-viewport-clamp` (default `92vw`) — the shared narrow-viewport ceiling the
+popup's max-inline-size is `min()`ed against, alongside its own `24rem` cap and the positioner's
+available space. See `lr-tour` for the shared-clamp note.
 
 **Optional peer deps:** none.
 
@@ -6585,12 +7677,31 @@ block, repeated three times, `data-field="day"|"month"|"year"`), `field-input` (
 small per-field text label), `hint`, `error` (`role="alert"`).
 
 **Themeable custom properties:** `--lr-known-date-field-padding-block`,
-`--lr-known-date-field-padding-inline`, `--lr-known-date-field-font-size` (all three rewritten by
-each `:host([size])` rule; `m` defaults `--lr-space-s`/`--lr-space-s`/`--lr-font-size-md-sm`),
+`--lr-known-date-field-padding-inline`, `--lr-known-date-field-font-size`,
+`--lr-known-date-field-min-height` (all four rewritten by
+each `:host([size])` rule; `m` defaults `--lr-space-s`/`--lr-space-s`/`--lr-font-size-md-sm`/
+`--lr-size-2-5rem`), `--lr-known-date-field-height`,
 `--lr-known-date-field-gap` (default `--lr-space-s` — gap between the three field blocks),
 `--lr-known-date-day-field-width` / `--lr-known-date-month-field-width` (default `--lr-size-3-5em`)
 and `--lr-known-date-year-field-width` (default `--lr-size-5em`) — the per-field input widths, not
-size-scaled.
+size-scaled. `--lr-known-date-invalid-border-color` (default `var(--lr-color-danger)`) — border
+color of each `field-input` while `:host([data-invalid])` is set. Component-scoped indirection over
+the shared `--lr-color-danger` token, so a consumer can retheme just this invalid-field border
+without repainting every other component that reads the same shared danger token.
+
+The two height knobs work as a pair on `[part='field-input']`, the same way
+`lr-input`/`lr-select`/`lr-combobox`/`lr-date-input` expose theirs:
+
+- `--lr-known-date-field-min-height` is a **floor**, re-assigned per `size` tier. Every tier's
+  default sits below the field's own padding/font-driven height, so raising it is what makes it
+  visible; lowering it changes nothing.
+- `--lr-known-date-field-height` pins an **exact** height (both floors and caps), so the three
+  inputs can line up with a neighbouring control of a known height. It is **undeclared by
+  default** — the field grows to fit its content. Never set it to `auto`: `auto` is a valid
+  declared value that wins over the `var()` fallback arm, which would make the per-tier floor
+  dead code. To go back to the default behavior, remove the declaration rather than neutralizing
+  it. Because the component never declares it, it can be set inline, from an ancestor, or from an
+  outer-tree rule.
 
 **Known gotchas:**
 - Field *order* is derived from the locale by formatting a probe date (Jan 2 2026) with
@@ -6727,7 +7838,17 @@ label switches to Done on the last step).
 `--lr-tour-spotlight-radius` (default `--lr-radius` — shared by the cutout and the ring),
 `--lr-tour-spotlight-ring-color` (default `--lr-color-brand`), `--lr-tour-spotlight-ring-width`
 (default `--lr-border-width-medium`), `--lr-tour-popover-max-width` (default `--lr-size-22rem`,
-further capped by `92vw` and the positioner's available space).
+further capped by `--lr-popover-viewport-clamp` and the positioner's available space),
+`--lr-tour-progress-dot-current-bg` (default `var(--lr-color-brand)`) — background of
+`progress-dot` for the current step. Component-scoped indirection over the shared `--lr-color-brand`
+token, so a consumer can retheme just the current-step dot without repainting every other component
+that reuses the same shared brand token.
+
+`--lr-popover-viewport-clamp` (default `92vw`, from `--lr-theme-popover-viewport-clamp`) is the
+shared ceiling that keeps any floating surface inside a narrow viewport. `lr-tour`,
+`lr-mention-popover`, and `lr-export-button` all `min()` their own max-inline-size against it, so
+retuning `--lr-theme-popover-viewport-clamp` once at `:root` narrows or widens all three together
+rather than per component.
 
 **Known gotchas:**
 - By default the spotlighted target is **non-interactive**: it stays visible and announceable (not
@@ -6800,7 +7921,45 @@ installed, renders an empty template (see gotchas).
 Also exported from the package root:
 `languageToCountry(language: string): string | undefined` and the `LANGUAGE_TO_COUNTRY` lookup
 table (region subtag wins, e.g. `en-US` → `us`; plain `en` → `gb`; override the table per-app if you
-need different defaults).
+need different defaults), plus `localeNativeName(tag: string): string`.
+
+`localeNativeName()` returns a BCP-47 tag's **endonym** — the locale's name written in that locale
+itself (`'fr'` → `français`, `'pt-BR'` → `português (Brasil)`). That is what a language switcher
+should list, so a reader who understands none of the current UI language can still find their own.
+It derives from `Intl.DisplayNames`, so no name table ships with the library and results follow the
+browser's own ICU data; the underlying instance comes from a shared memoized cache, since a picker
+does one lookup per offered locale on every render pass. A tag with no display name resolves to the
+tag itself, and so does a structurally invalid one — `Intl.DisplayNames` throws a `RangeError` on
+those rather than falling back, and a language picker should degrade to showing the raw tag rather
+than tearing down the render. Pair it with `languageToCountry()` for the flag half of the same row.
+
+**Locale picker recipe.** A locale picker is a composition, not a component: `<lr-popover>` supplies
+the light-dismiss surface, `<lr-flag>` the country mark, `localeNativeName()` the endonym, and
+`aria-current="true"` marks the active choice. Which locales exist is the app's decision, so the app
+owns the list. Set `lang` on each row so assistive tech pronounces the endonym in its own language,
+and use `variant="compact"` at icon scale.
+
+```html
+<lr-popover placement="bottom-start">
+  <button slot="trigger">
+    <lr-flag language="fr" label="" style="height: 1rem"></lr-flag>
+    <span>français</span>
+  </button>
+  <ul role="list">
+    <!-- one <li><button lang="pt-BR" aria-current="false"> … </button></li> per offered locale -->
+  </ul>
+</lr-popover>
+```
+
+```js
+import { localeNativeName, languageToCountry } from '@aceshooting/lyra-ui';
+
+const rows = ['en', 'fr', 'de', 'pt-BR', 'ja', 'ar'].map((tag) => ({
+  tag,
+  name: localeNativeName(tag),   // endonym, e.g. "português (Brasil)"
+  country: languageToCountry(tag), // flag code for the same row
+}));
+```
 
 ```html
 <lr-flag country="fr" label="France"></lr-flag>
@@ -6982,7 +8141,9 @@ exists and was hit)
 
 **Slots:** none.
 
-**CSS parts:** `base`, `container`, `legend`, `legend-swatch`
+**CSS parts:** `base`, `container`, `legend`, `legend-swatch`, `error` (`role="alert"` message
+rendered in place of `container` if the optional `maplibre-gl` peer dependency fails to load, e.g.
+not installed)
 
 **Themeable custom properties:** shared tokens only — `--lr-space-xs/-s`, `--lr-color-surface`,
 `--lr-color-border`, `--lr-shadow`, `--lr-radius`.
@@ -7059,6 +8220,10 @@ parsing (that's left entirely to the host).
 - `maxFileSize: number = 0` (attribute `max-file-size` — bytes; `0` disables the check)
 - `directory: boolean = false` (reflected) — enables native directory selection where supported
 - `paste: boolean = true` (reflected) — accepts files pasted into the dropzone
+- `compact: boolean = false` (reflected) — tighter dropzone padding, gap and label font for
+  constrained spaces (a toolbar, a table cell) — the same convention as `lr-empty`'s `compact`. The
+  dashed border stays; only the internal spacing shrinks. `false` (the default) keeps the full
+  `--lr-space-l` dropzone.
 - `label: string = 'Drop files here or click to browse'`
 - `accessibleLabel: string = ''` (attribute `aria-label`) — overrides `label` as the internal
   dropzone/button accessible name without changing visible copy
@@ -7085,9 +8250,22 @@ announces correctly.
 **CSS parts:** `base`, `input`, `status` (a visually-hidden `role="status" aria-live="polite"`
 element carrying the drag accept/reject announcement)
 
-**Themeable custom properties:** shared tokens only — `--lr-space-xs`, `--lr-space-l`,
+**Themeable custom properties:** `--lr-file-input-compact-padding` (default `var(--lr-space-s)`) —
+`[part='base']`'s padding while `compact`; `--lr-file-input-compact-gap` (default
+`var(--lr-space-2xs)`) — the gap between the dropzone's slotted children while `compact`; and
+`--lr-file-input-compact-font-size` (default `var(--lr-font-size-sm)`) — the label's font size while
+`compact`. All three apply only while `compact` is set, so they are the way to tune a dense dropzone
+without re-pointing shared spacing tokens for everything else on the page. The drag accept/reject
+highlight on `[part='base'][data-drag-state='accept'|'reject']` is independently overridable too:
+`--lr-file-input-accept-border-color` (default `var(--lr-color-success)`) and
+`--lr-file-input-accept-bg` (default `color-mix(in srgb, var(--lr-color-success) 8%, transparent)`)
+for the drag-accept state; `--lr-file-input-reject-border-color` (default `var(--lr-color-danger)`)
+and `--lr-file-input-reject-bg` (default `color-mix(in srgb, var(--lr-color-danger) 8%,
+transparent)`) for drag-reject. All four are inline `var()` fallbacks at the point of use, settable
+on the element or any ancestor, so a consumer can retint just this dropzone's drag highlight without
+hijacking the shared `--lr-color-success`/`--lr-color-danger` tokens used elsewhere. Plus shared
+tokens — `--lr-space-xs`, `--lr-space-l`,
 `--lr-color-border`, `--lr-radius`, `--lr-color-surface`, `--lr-color-text-quiet`,
-`--lr-color-success` (drag-accept state), `--lr-color-danger` (drag-reject state),
 `--lr-focus-ring-width/-color/-offset` (`[part="base"]:focus-visible` outline),
 `--lr-opacity-disabled` (`:host([disabled])` dimming).
 
@@ -7375,6 +8553,11 @@ final.
   overrides the `--lr-media-card-max-height` custom property for this instance only (applied
   inline on `[part="base"]`, so it reliably wins over a `:host{}`-declared default from outside the
   shadow root) — same contract as `<lr-document-preview>`'s identically-named prop.
+- `appearance: 'card' | 'plain' = 'card'` (reflected) — visual chrome, mirroring
+  `<lr-source-card>`'s `appearance` vocabulary. `'card'` (the default) keeps the bordered, filled
+  box. `'plain'` removes `[part="base"]`'s border, background, padding, and corner radius, so a
+  card inside a dense chat transcript (or any container already drawing its own separation between
+  attachments) doesn't double the frame.
 
 **Events:** `lr-open` (`detail: { src: string; filename: string }`, cancelable) — fired when the
 card (or, for `kind="video"`, its separate `open-button`) is activated. `detail.src` is whichever
@@ -7564,8 +8747,12 @@ initials text, rendered whenever neither `icon` nor `image` is).
 **Themeable custom properties:** `--lr-avatar-size` (default `2rem`, swapped to `1.5rem`/`2.5rem`
 per `size="sm"`/`"lg"`), `--lr-avatar-bg` (default `var(--lr-color-surface-alt,
 var(--lr-color-border))`, swapped per `tone`), `--lr-avatar-color` (default
-`var(--lr-color-text)`, swapped per `tone`), plus shared tokens `--lr-radius`/`-pill`,
-`--lr-font-size-sm`, `--lr-font-weight-semibold`.
+`var(--lr-color-text)`, swapped per `tone`), `--lr-avatar-font-size` (default
+`var(--lr-font-size-sm)`) — the font size of the initials fallback, and of any `em`-sized slotted
+glyph. `size` swaps it per tier too (`var(--lr-font-size-xs)` at `sm`, `var(--lr-font-size-md)` at
+`lg`), so the initials track the circle instead of staying one fixed size across every tier;
+override it on the element for a size the built-in scale doesn't cover. Plus shared tokens
+`--lr-radius`/`-pill`, `--lr-font-size-sm`, `--lr-font-weight-semibold`.
 
 **Optional peer deps:** none.
 
@@ -7735,7 +8922,12 @@ under `dir="rtl"` — setting `0` or a positive length turns the stack into norm
 `--lr-avatar-group-ring-color` (default `var(--lr-color-surface)`),
 `--lr-avatar-group-ring-width` (default `var(--lr-border-width-medium)`),
 `--lr-avatar-group-badge-bg` (default `var(--lr-color-border)`, swapped per `tone`),
-`--lr-avatar-group-badge-color` (default `var(--lr-color-text)`, swapped per `tone`).
+`--lr-avatar-group-badge-color` (default `var(--lr-color-text)`, swapped per `tone`),
+`--lr-avatar-group-badge-font-size` (default `var(--lr-font-size-sm)`) — the font size of the "+N"
+badge label. `size` swaps it per tier (`var(--lr-font-size-xs)` at `sm`, `var(--lr-font-size-md)` at
+`lg`), matching `<lr-avatar>`'s own `--lr-avatar-font-size` scale so the badge and the avatars it
+caps read at the same optical weight; override it alongside `--lr-avatar-font-size` on the avatars
+themselves when tuning a custom tier.
 
 **Optional peer deps:** none.
 
@@ -7843,7 +9035,12 @@ documents) and `<lr-image-comparer>` (before/after slotted surfaces). Adopts `Do
 with `anchorKinds: ['region']` only — no text selection is bound.
 
 **Properties:** `src: string = ''`, `name: string = ''`, `alt?: string`, `fit: 'contain' | 'width' |
-'actual' = 'contain'` (reflected), `zoom: number = 1` (reflected), `rotation: 0 | 90 | 180 | 270 = 0`
+'actual' = 'contain'` (reflected), `zoom: number = 1` (reflected), `minZoom: number = 0.5` (attribute
+`min-zoom`), `maxZoom: number = 4` (attribute `max-zoom`), `zoomStep: number = 0.25` (attribute
+`zoom-step`) — `minZoom`/`maxZoom`/`zoomStep` are pure pass-throughs to the embedded
+`<lr-zoomable-frame>` as its own `.minZoom`/`.maxZoom`/`.zoomStep`, which does the actual
+clamping/normalizing; same names/defaults as `<lr-lightbox>`'s identical trio, both wrapping the
+same pan/zoom surface — `rotation: 0 | 90 | 180 | 270 = 0`
 (reflected), and `annotatable: boolean = false` (reflected).
 
 **Methods:** `rotate()` advances `rotation` by 90°. `zoomIn()`, `zoomOut()`, and `resetZoom()` adjust
@@ -7859,6 +9056,20 @@ zoom }`), `lr-rotation-change` (`detail: { rotation }`), `lr-fit-change` (`detai
 embedded `lr-zoomable-frame`), `image-wrapper`, `image`, `highlight-layer`, `highlight` (carries
 `data-tone`/`data-active`), `highlight-label`, `annotation-box`, and `error`.
 
+**Themeable custom properties:** `--lr-image-viewer-annotate-active-bg` (default
+`var(--lr-color-brand-quiet)`) and `--lr-image-viewer-annotate-active-border` (default
+`var(--lr-color-brand)`) — the background and border of `[part='annotate-toggle']` while annotation
+mode is on. The toggle carries its own glyph in `--lr-color-text`, so keep a 4.5:1 ratio against it
+when overriding the background. `--lr-image-viewer-highlight-active-color` (default
+`var(--lr-color-brand)`) — the outline of the `[part='highlight']` matching `activeHighlightId`,
+independent of the per-tone border colors, so the active box stays distinguishable whatever tone it
+carries. All three are declared as inline `var()` fallbacks at the point of use rather than on
+`:host`, so each can be set on the element *or on any ancestor*: `::part(highlight)[data-active]` is
+invalid CSS — Shadow Parts forbids an attribute selector after `::part()` — which previously left
+overriding the library-wide `--lr-color-brand`/`--lr-color-brand-quiet` tokens as the only lever,
+repainting every other element that read them. Unset, each falls back to the token its rule used
+before.
+
 ## `lr-av-player`
 
 An audio/video player built on a native `<audio>`/`<video>` element, plus a cue transcript synced to
@@ -7892,11 +9103,47 @@ found }`), `lr-search-change` (`detail: { query, matchCount, activeIndex }`), an
 **CSS parts:** `base`, `media` (the native `<audio>`/`<video>` element), `toolbar`, `rate-select`,
 `timeline` (click-to-seek and arrow-key seeking), `timeline-marker` (one per `time-range` highlight;
 `data-tone`, `data-active`), `transcript` (the `<lr-virtual-list>` itself), `cue` (`aria-current`,
-`data-match`, `data-active-match`), `cue-time`, `cue-speaker`, `cue-text`, and `error`.
+`data-match`, `data-active-match`), `cue-current` (added alongside `cue` on the row the playhead is
+inside), `cue-match` (added alongside `cue` on a row matching the current search query),
+`cue-active-match` (added alongside `cue`/`cue-match` on the row holding the current match),
+`cue-time`, `cue-speaker`, `cue-text`, and `error`.
+
+Every cue-level part above is rendered into the embedded `<lr-virtual-list>`'s own shadow root and
+forwarded back out through `exportparts`, so `lr-av-player::part(cue)` and friends work from a
+consumer stylesheet. The three cue states are separate part *names* rather than attribute selectors,
+because Shadow Parts forbids an attribute selector after `::part()` —
+`::part(cue)[aria-current='true']` is invalid CSS, so use `::part(cue-current)`. The `aria-current`
+and `data-*` attributes remain on each row for semantics and scripting.
 
 **Themeable custom properties:** `--lr-av-player-transcript-height` (default
 `var(--lr-size-16rem)` — block size of the transcript pane; forwarded to the embedded
-`<lr-virtual-list>`'s own `--lr-virtual-list-height`).
+`<lr-virtual-list>`'s own `--lr-virtual-list-height`). `--lr-av-player-marker-active-color` (default
+`var(--lr-color-brand)`) — the outline of the `[part='timeline-marker']` matching
+`activeHighlightId`, leaving the per-tone marker fills alone. It 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(timeline-marker)[data-active]` is invalid CSS (Shadow Parts forbids an attribute
+selector after `::part()`), so re-pointing the shared `--lr-color-brand` token was the only previous
+lever.
+
+Each `[part='timeline-marker']`'s own background is independently overridable per tone, the same
+inline-`var()`-fallback pattern as `--lr-av-player-marker-active-color` above:
+`--lr-av-player-marker-bg` (default `color-mix(in srgb, var(--lr-color-brand) 35%, transparent)`) —
+no (or an unrecognized) `data-tone`; `--lr-av-player-marker-success-bg` (default `color-mix(in srgb,
+var(--lr-color-success) 35%, transparent)`) — `data-tone="success"`;
+`--lr-av-player-marker-warning-bg` (default `color-mix(in srgb, var(--lr-color-warning) 35%,
+transparent)`) — `data-tone="warning"`; `--lr-av-player-marker-danger-bg` (default `color-mix(in
+srgb, var(--lr-color-danger) 35%, transparent)`) — `data-tone="danger"`; and
+`--lr-av-player-marker-neutral-bg` (default `color-mix(in srgb, var(--lr-color-text) 25%,
+transparent)`) — `data-tone="neutral"`. Each can be set on the element or on any ancestor without
+hijacking the shared `--lr-color-success`/`-warning`/`-danger`/`-brand`/`-text` tokens used
+elsewhere in the theme.
+
+Two further cue-state properties tint the transcript: `--lr-av-player-cue-current-bg` (default
+`var(--lr-color-brand-quiet)`) is the background of the `cue-current` row the playhead is inside,
+and `--lr-av-player-cue-active-match-color` (default `var(--lr-color-warning)`) is the outline of
+the `cue-active-match` row, leaving the other matches' dashed outline on the shared warning token.
+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.
 
 # Charts (`components/charts/`)
 
@@ -7963,7 +9210,8 @@ number, label: string | undefined, value: unknown }`)
 optional overlay content positioned at the chart area's center, useful for doughnut and pie totals.
 
 **CSS parts:** `base`, `canvas`, `reset-zoom-button`, `description`, `data-table`, `center` (the
-chart-area-centered wrapper for the `center` slot)
+chart-area-centered wrapper for the `center` slot), `error` (`role="alert"` message rendered in
+place of `canvas` when the optional `chart.js` peer dependency fails to load)
 
 **Themeable custom properties:** `--lr-chart-height` (set programmatically on the host from the
 `height` property — must be read from the host, not a shadow-tree descendant, since custom
@@ -8196,7 +9444,9 @@ index, label, value }`).
 
 **Slots:** `data-table`, `center`.
 
-**CSS parts:** `base`, `canvas`, `reset-zoom-button`, `description`, `data-table`, `center`.
+**CSS parts:** `base`, `canvas`, `reset-zoom-button`, `description`, `data-table`, `center`,
+`error` (`role="alert"` message rendered in place of `canvas` when the optional `chart.js` peer
+dependency fails to load — see `llms/components/lr-chart.md`).
 
 **Themeable custom properties:** `--lr-chart-height`, `--lr-chart-grid-color`,
 `--lr-chart-tick-color`, `--lr-chart-legend-color`, `--lr-chart-tooltip-bg`,
@@ -8257,7 +9507,9 @@ and `label` the generated bucket range string (`"lo–hi"`, both bounds at one d
 
 **Slots:** `data-table`, `center`.
 
-**CSS parts:** `base`, `canvas`, `reset-zoom-button`, `description`, `data-table`, `center`.
+**CSS parts:** `base`, `canvas`, `reset-zoom-button`, `description`, `data-table`, `center`,
+`error` (`role="alert"` message rendered in place of `canvas` when the optional `chart.js` peer
+dependency fails to load — inherited from `LyraChart`, unaffected by the binning logic).
 
 **Themeable custom properties:** `--lr-chart-height`, `--lr-chart-grid-color`,
 `--lr-chart-tick-color`, `--lr-chart-legend-color`, `--lr-chart-tooltip-bg`,
@@ -8445,7 +9697,15 @@ SFMono-Regular, Menlo, Consolas, monospace`) and `--lr-document-preview-spin-dur
 `0.8s`, stopped under reduced motion). `--lr-document-preview-progress` (default `0`) — a unitless
 0–100 number the determinate spinner's `conic-gradient` fill reads; written inline on the ring by
 the component itself from the clamped `progress` property, so overriding it only makes sense to
-repaint the fraction. Plus shared tokens
+repaint the fraction. `--lr-document-preview-active-border` (default
+`var(--lr-color-warning, var(--lr-color-brand))`) — the border color of the `[part='region-highlight']`
+matching `activeHighlightId` (image format only), deliberately distinct from the resting highlight
+border so the active region can be recolored without touching the rest. Like the library's other
+state hooks it 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(region-highlight)[data-active]` is
+invalid CSS (Shadow Parts forbids an attribute selector after `::part()`), which previously left
+re-pointing the shared `--lr-color-warning`/`--lr-color-brand` tokens as the only lever, repainting
+every other element that read them. Plus shared tokens
 `--lr-color-border`, `--lr-radius`, `--lr-color-surface`, `--lr-space-s/-m/-l/-xs`,
 `--lr-color-text`, `--lr-color-text-quiet`, `--lr-color-danger`, `--lr-color-brand`,
 `--lr-color-on-brand`, `--lr-focus-ring-width/-color/-offset`, `--lr-transition-fast`.
@@ -8661,9 +9921,10 @@ localized show/hide toggle. `false` (the default) preserves the full body render
 **CSS parts:** `base`, `headers`, `from-label`, `from`, `to-label`, `to`, `subject-label`, `subject`,
 `date-label`, `date`, `body`, `body-html`, `body-text`, `attachments`, `attachments-label`,
 `attachment-list`, `attachment-item`, `attachment-button` (an attachment's open button, inside its
-`attachment-item`), `quoted` (a folded quoted-text block, hidden until expanded, only
-while `foldQuotes`), `quote-toggle` (the show/hide-quoted-text toggle button, only while `foldQuotes`),
-`spinner`, and `error`.
+`attachment-item`), `attachment-name` (an attachment's filename, inside `attachment-button`),
+`attachment-size` (an attachment's formatted file size, inside `attachment-button`), `quoted` (a
+folded quoted-text block, hidden until expanded, only while `foldQuotes`), `quote-toggle` (the
+show/hide-quoted-text toggle button, only while `foldQuotes`), `spinner`, and `error`.
 
 **Themeable custom properties:** `--lr-email-viewer-max-height` (default `none`) — maximum block size
 of `[part="body"]`; also settable via the `max-height` property, which writes this token inline.
@@ -8710,7 +9971,13 @@ listing region as `role="region"`; with neither set, the region is unnamed.
 
 **Events:** `lr-render-error` with `detail.error` when fetching or parsing fails.
 
-**CSS parts:** `base`, `entry`, `entry-icon`, `entry-name`, `entry-size`, `spinner`, and `error`.
+**CSS parts:** `base`, `entry`, `entry-icon`, `entry-name`, `entry-name-dir`, `entry-size`,
+`spinner`, and `error`. A directory row's name element carries both `entry-name` and
+`entry-name-dir` (a part list), so `::part(entry-name-dir)` selects only directory names while
+`::part(entry-name)` still selects every name. Entry rows are rendered into the embedded
+`<lr-virtual-list>`'s own shadow root and forwarded with `exportparts`, so
+`lr-archive-viewer::part(entry)` (and every other row part above) reaches them from a consuming
+stylesheet.
 
 **Exports:** `ArchiveEntry` — `{ name: string; dir: boolean; size: number }`.
 
@@ -8825,6 +10092,14 @@ rendered region highlight), `region-highlight` (one region highlight, `data-tone
 
 **Themeable custom properties:** `--lr-svg-viewer-max-height` (default `none`) — maximum block size
 of `[part="body"]`; also settable via the `max-height` property, which writes this token inline.
+`--lr-svg-viewer-active-border` (default `var(--lr-color-warning, var(--lr-color-brand))`) — the
+border color of the `[part='region-highlight']` matching `activeHighlightId`, distinct from the
+resting highlight border so the active region can be recolored without touching the rest. It 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(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.
 
 **Optional peer dependency:** `dompurify`.
 
@@ -8881,7 +10156,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>[] }`.
 
@@ -8937,8 +10215,11 @@ drag* over a highlighted passage never activates it — the selection-in-progres
 to tell that apart from a genuine activation click.
 
 **Properties:** `src` and `name` are strings. `page: number = 1` is the one-based current page and
-`zoom: number = 1` is clamped to `0.25`–`4`. `anchorKinds` is a readonly `['page', 'text-quote',
-'region']` (this viewer's supported `LyraAnchor.kind` values for the shared anchor-target contract).
+`zoom: number = 1` is clamped to `0.25`–`4`. `maxHeight: string = ''` (attribute `max-height`) is a
+CSS length that, once set, overrides `--lr-pdf-viewer-height` — the block size of the virtualized
+page list — declaratively, writing it inline on `[part="base"]`. `anchorKinds` is a readonly
+`['page', 'text-quote', 'region']` (this viewer's supported `LyraAnchor.kind` values for the shared
+anchor-target contract).
 
 **Events:**
 - `lr-render-error` — `detail: { error }` — fetching, parsing, or rendering (page canvas or text
@@ -8970,15 +10251,28 @@ table of contents as `PdfOutlineItem[]` (`{ title, page?, children? }`), `[]` wh
 `clearSearch()`); `searchNext()` and `searchPrevious()` advance/step back through matches (wrapping,
 resolving `false` when there are none); `clearSearch()` clears the query, matches, and painted marks.
 
-**CSS parts:** `base`, `toolbar`, `page-indicator`, `zoom-indicator`, `pages`, `page`, `text-layer`,
-`search-match` (a `<mark>` painted into a mounted page's text layer around one search match),
-`search-match-active` (the currently active match, also carries `search-match`), `spinner`, and
-`error`. Search painting is best-effort: a page outside the virtualized render window is skipped and
-repainted once its text layer mounts, and a match spanning a text-layer span boundary that
-`Range.surroundContents()` can't wrap stays unpainted (still reachable via `searchNext()`).
+**CSS parts:** `base`, `toolbar`, `page-indicator`, `zoom-indicator`, `pages`, `page`, `page-canvas`
+(the canvas one page's content is painted onto), `text-layer`, `text-span` (one generated text run
+inside a page's text layer — PDF.js creates these imperatively, and they carry the part so a rule can
+reach them without a descendant combinator), `search-match` (a `<mark>` painted into a mounted page's
+text layer around one search match), `search-match-active` (the currently active match, also carries
+`search-match`), `spinner`, and `error`. Search painting is best-effort: a page outside the
+virtualized render window is skipped and repainted once its text layer mounts, and a match spanning a
+text-layer span boundary that `Range.surroundContents()` can't wrap stays unpainted (still reachable
+via `searchNext()`).
+
+`page`, `page-canvas`, `text-layer`, `text-span`, `search-match` and `search-match-active` are
+rendered inside the virtualizing `lr-virtual-list`'s own shadow root and forwarded out through
+`exportparts`, so `lr-pdf-viewer::part(page)` (and each of the others) works from a consumer
+stylesheet exactly like the parts in this viewer's own shadow root. The selection tint over a page's
+text is styled on `text-span` rather than on `text-layer`, because a highlight pseudo-element is
+matched against the element the selected text originates in:
+`lr-pdf-viewer::part(text-span)::selection { background: … }`.
 
 **Themeable custom properties:** `--lr-pdf-viewer-height` (default `var(--lr-size-24rem)`) — block
-size of the virtualized page list (`[part="pages"]`).
+size of the virtualized page list (`[part="pages"]`); also settable via the `maxHeight` property,
+which writes this token inline on `[part="base"]`. Everything below the page list is retuned
+through the exported parts above rather than through dedicated custom properties.
 
 **Optional peer dependency:** install `pdfjs-dist` with `pnpm add pdfjs-dist`. The component registers
 a lazy `application/pdf` renderer with `<lr-document-viewer>` so the PDF library is loaded only when
@@ -9016,7 +10310,16 @@ Enter/Space. `lr-anchor-result` (`detail: { found }`) — fired after an `anchor
 `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`.
+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
+`exportparts`, so `lr-spreadsheet-viewer::part(cell)` reaches them from a consumer stylesheet.
+
+**Themeable custom properties:** `--lr-spreadsheet-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 `xlsx` with `pnpm add https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz`. The official CDN matches the
 `.xlsx` and `.xls` MIME types and filename extensions.
@@ -9036,8 +10339,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
@@ -9052,7 +10357,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.
@@ -9144,12 +10460,23 @@ truth.
 `detail: { page }`. In wired mode the rail also sets `viewer.page` itself.
 
 **CSS parts:** `base` (the rail), `pages` (the embedded `<lr-virtual-list>`), `page` (one page
-button), `thumbnail` (the thumbnail canvas wrapper), `page-number` (the visible page number), `heat`
-(the heat-marker cluster), and `heat-dot` (one tone-colored heat marker, or the `+n` overflow
+button), `page-current` (the button for the current `page`), `thumbnail` (the thumbnail canvas
+wrapper), `page-number` (the visible page number), `heat` (the heat-marker cluster), `heat-dot` (one
+heat marker), `heat-dot-accent`, `heat-dot-success`, `heat-dot-warning`, `heat-dot-danger` and
+`heat-dot-neutral` (the tone-specific name on each marker), and `heat-dot-overflow` (the `+n`
 marker).
 
+Page rows are rendered into the embedded `<lr-virtual-list>`'s own shadow root and forwarded with
+`exportparts`, so `lr-page-rail::part(page)` and the rest reach them from a consuming stylesheet.
+State variants each carry a second name in the element's part list rather than a state attribute,
+because `::part()` cannot be followed by an attribute selector: the current row is
+`part="page page-current"` and a danger marker is `part="heat-dot heat-dot-danger"`, and `::part()`
+matches with `part~=` semantics, so both names select the same element.
+
 **Themeable custom properties:** `--lr-page-rail-height` (default `var(--lr-size-24rem)`) — block
-size of the virtualized rail.
+size of the virtualized rail. `--lr-page-rail-current-bg` (default `var(--lr-color-brand-quiet)`) —
+background of the `page-current` button, kept while the row is hovered so the current page stays
+identifiable under the pointer.
 
 ## `lr-notebook-viewer`
 
@@ -9187,11 +10514,26 @@ activeIndex }`. `lr-render-error` — `detail: { error }`, fetching, parsing, or
 notebook failed.
 
 **CSS parts:** `base` (the root scroll container), `cell` (`data-cell-type="code|markdown|raw"`,
-`data-active`), `cell-gutter` (the `In [n]`/`Out [n]` label column), `cell-source`, `outputs`,
-`output` (`data-output-type`, `data-stream`), `output-toggle`, `error`, `spinner`.
+`data-active`), `cell-active` (added alongside `cell` on the cell an anchor currently targets),
+`cell-gutter` (the `In [n]`/`Out [n]` label column), `cell-source`, `outputs`, `output`
+(`data-output-type`, `data-stream`), `output-error` (added alongside `output` on a stderr stream or
+an error output), `error-output-label` (the label introducing an error output's traceback),
+`output-toggle`, `error`, `spinner`.
+
+Every cell-level part above is rendered into the embedded `<lr-virtual-list>`'s own shadow root and
+forwarded back out through `exportparts`, so `lr-notebook-viewer::part(cell)` and friends work from
+a consumer stylesheet. The three state variants are separate part *names* rather than attribute
+selectors, because Shadow Parts forbids an attribute selector after `::part()` —
+`::part(cell)[data-active]` is invalid CSS, so use `::part(cell-active)`. The `data-*` attributes
+remain on the elements for scripting.
 
 **Themeable custom properties:** `--lr-notebook-viewer-max-height` (default `none`).
 
+`--lr-notebook-viewer-active-bg` (default `var(--lr-color-brand-quiet)`) is the background of the
+cell currently targeted by an anchor — the `cell-active` part. It 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.
+
 **Optional peer deps:** `marked`+`dompurify` (markdown cells, falls back to plain text per cell),
 `shiki` (code cells, falls back to unhighlighted), `dompurify` (HTML/SVG outputs, falls back to
 `text/plain`).
@@ -9241,7 +10583,30 @@ the resolved anchor target, `data-match`, `data-active-match`), `tag` (`data-mat
 `toggle` (an element's expand/collapse button, hidden but present for row alignment on leaf/empty
 elements), `error`, `spinner`.
 
-**Themeable custom properties:** `--lr-xml-viewer-max-height` (default `none`).
+**Themeable custom properties:** `--lr-xml-viewer-max-height` (default `none`) — maximum block size
+of the scrollable body; also settable via the `max-height` property.
+`--lr-xml-viewer-active-match-color` (default `var(--lr-color-warning)`) — the solid outline on the
+`[part='node']` holding the *current* search match, leaving every other match on its dashed
+`--lr-xml-viewer-match-color` outline. It 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(node)[data-active-match]` is invalid CSS — Shadow Parts forbids an attribute selector after
+`::part()` — so distinguishing the active match previously meant re-pointing the shared
+`--lr-color-warning` token, which recolored every other match (and every other warning surface)
+along with it. Unset, it falls back to that token, so rendering is unchanged.
+
+`--lr-xml-viewer-match-color` (default `var(--lr-color-warning)`) — outline color of a non-active
+`[part='node']` search match, and (via `color-mix`) the tint source for a matching `[part='text']`'s
+background — kept distinct from `--lr-xml-viewer-active-match-color` so the non-active matches can
+be recolored without touching the active one. `--lr-xml-viewer-match-bg` (default
+`var(--lr-color-warning-quiet)`) — background of a matching `[part='tag']`/`[part='attribute-value']`.
+Both are inline `var()` fallbacks at the point of use, so either can be set on the element or any
+ancestor; unset, they fall back to the same shared tokens the rules used before.
+
+`[part='toggle']`'s glyph box stays compact (`1.25rem`) while its *interactive* box takes the shared
+minimum target size as a floor via `--lr-icon-button-size`. That token is a floor, not a fixed size,
+so lowering it never squashes the chevron below its own box — the visible glyph keeps its size while
+the hit target follows the token, and it can never fall under the accessible minimum from this
+component's own rules.
 
 ```html
 <lr-xml-viewer .xml=${payload} collapsed-depth="2" copyable
@@ -9401,7 +10766,8 @@ carrying `data-display="inline"|"block"`)
 
 **Themeable custom properties:** `--lr-markdown-font-mono` (default `ui-monospace, SFMono-Regular,
 Menlo, Consolas, monospace` — the code/code-block font; component-specific since no shared
-`--lr-*` monospace token exists), plus shared tokens `--lr-space-xs/-s/-m/-l`,
+`--lr-*` monospace token exists), `--lr-code-block-tab-size` (default `2` — tab width inside a
+rendered fenced or indented `code-block`), plus shared tokens `--lr-space-xs/-s/-m/-l`,
 `--lr-color-brand-quiet`, `--lr-color-brand`, `--lr-color-border`, `--lr-color-text-quiet`,
 `--lr-radius`.
 
@@ -9437,6 +10803,17 @@ cleared in `updated()` based on whether the deps have loaded) and shows the same
 rendering — there's no separate loading skeleton, since the un-rendered Markdown source is already
 legible text in the meantime.
 
+**One tab width for every code surface.** `--lr-code-block-tab-size` is deliberately the same
+property name and default (`2`) that `<lr-code-block>` and `<lr-code-editor>` use, so a consumer sets
+tab width once for every code surface in the app. It is declared as a `var()` fallback **at the point
+of use, never on `:host`** — a `:host` declaration is re-stamped on every instance and shadows any
+inherited value, so a page- or container-level declaration could never reach it. This element carries
+its own copy of that fallback rather than inheriting `<lr-code-block>`'s because the two are
+**sibling** custom elements, not ancestor and descendant: no single declaration inside one of them
+can cover the other. The same value can still *look* different between the two — a markdown code
+block inherits `white-space: pre-wrap` while `<lr-code-block>` is `white-space: pre`, and tab stops
+restart at the beginning of each visual line, so a wrapped line's tabs land differently.
+
 **Known gotchas:**
 - a malformed percent-escape or lone UTF-16 surrogate in a link's raw `href` makes the internal
   `encodeURI`-based validity guard throw, silently dropping just that anchor (the link text still
@@ -9499,6 +10876,15 @@ unhighlighted permanently, `headingAnchors: boolean = false` (attribute `heading
 **CSS parts:** `content`, `heading`, `paragraph`, `list`, `code-block`, `inline-code`, `link`,
 `table`, `blockquote`, `img`, `math` — identical to `<lr-markdown>`'s own parts.
 
+**Themeable custom properties:** `--lr-code-block-tab-size` (default `2` — tab width inside a
+rendered fenced or indented `code-block`), with exactly the mechanics described under
+`<lr-markdown>` above: the same property name and default that `<lr-code-block>`/`<lr-code-editor>`
+read, declared as a `var()` fallback at the point of use rather than on `:host` so a page- or
+container-level value reaches it, and carried here in its own right because this element is a
+**sibling** of `<lr-code-block>` rather than an ancestor of it. Markdown code blocks wrap
+(`white-space: pre-wrap`) while `<lr-code-block>` does not, so the same tab width can render
+differently on a wrapped line.
+
 **Optional peer deps:** `marked`, `dompurify` (both lazy-loaded, same as `<lr-markdown>`), `katex`
 (for `math`). Does *not* depend on the full `shiki` package's default entry point — only
 `shiki/core`/`shiki/engine/oniguruma`/`shiki/langs/*`, the same fine-grained subset
@@ -9595,6 +10981,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-*`,
@@ -9741,6 +11143,10 @@ reveals the invalid state, and `form.reset()` clears the touched presentation.
 - `maxRows: number = 8` (attribute `max-rows`) — floored to at least `minRows`
 - `status: ChatComposerStatus = 'idle'` (reflected) — `'idle' | 'sending' | 'streaming'`; drives the
   built-in button's icon/label (send vs. stop) and whether Enter still submits
+- `appearance: ChatComposerAppearance = 'card'` (reflected) — `'card' | 'plain'`; `'plain'` drops
+  `[part="base"]`'s border, background, padding and corner radius so a composer docked inside a chat
+  panel, dialog footer or toolbar that already draws its own border doesn't double the frame. The
+  focus affordance is swapped, not dropped — see **Known gotchas**
 - `submitOnEnter: boolean = true` (reflected, attribute `submit-on-enter`) — when `false`, Enter
   always inserts a newline instead of submitting
 - `submitDisabled: boolean = false` (reflected, attribute `submit-disabled`) — consumer-controlled
@@ -9784,11 +11190,15 @@ entirely when it has assigned content)
 
 **CSS parts:** `base`, `chips`, `row`, `leading`, `textarea`, `trailing`, `action-button`
 
-**Themeable custom properties:** no component-specific custom properties; consumes shared tokens
-`--lr-space-xs`, `--lr-space-s`, `--lr-color-border`, `--lr-color-surface`,
-`--lr-color-brand`, `--lr-color-on-brand`, `--lr-color-text-quiet`, `--lr-radius`,
-`--lr-icon-button-size`, `--lr-transition-fast`, `--lr-opacity-disabled`,
-`--lr-focus-ring-width`, `--lr-focus-ring-color`, `--lr-focus-ring-offset`.
+**Themeable custom properties:** `--lr-chat-composer-busy-bg` (default `var(--lr-color-text-quiet)`)
+— `[part="action-button"]`'s background while `status` is `"sending"` or `"streaming"` (the busy/stop
+treatment). Scoped separately from the shared `--lr-color-text-quiet` token, which
+`[part="textarea"]`'s placeholder color also reads — overriding this cssprop recolors only the busy
+button, not the placeholder too (the same shared-token-collision fix `<lr-chat-message>`'s own
+user-bubble background pair documents). Plus shared tokens `--lr-space-xs`, `--lr-space-s`,
+`--lr-color-border`, `--lr-color-surface`, `--lr-color-brand`, `--lr-color-on-brand`,
+`--lr-color-text-quiet`, `--lr-radius`, `--lr-icon-button-size`, `--lr-transition-fast`,
+`--lr-opacity-disabled`, `--lr-focus-ring-width`, `--lr-focus-ring-color`, `--lr-focus-ring-offset`.
 
 **Optional peer deps:** none.
 
@@ -9844,6 +11254,11 @@ and disables only the built-in Send button; editing and busy-state Stop behavior
 - `[part="chips"]`/`[part="leading"]` are hidden via a JS-tracked `[hidden]` attribute rather than a
   CSS `:empty` selector, because each always contains a literal `<slot>` child regardless of
   assigned content.
+- Under `appearance="card"` the only focus affordance is a border-color shift on `[part="base"]`
+  (the internal `<textarea>` sets `outline: none`). `appearance="plain"` removes that border, so it
+  swaps in a different affordance rather than losing focus visibility: an underline across the whole
+  input row, drawn as an inset `box-shadow` from `--lr-focus-ring-width`/`--lr-focus-ring-color` so
+  it costs no layout. If you restyle `[part="base"]` under `plain`, keep a focus indicator.
 
 ---
 
@@ -9986,6 +11401,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
@@ -10021,7 +11445,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`.
 
@@ -10068,6 +11518,11 @@ 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.
 
 ---
 
@@ -10123,10 +11578,24 @@ emitting `lr-change`.
 - `disabled: boolean = false` (reflected)
 - `required: boolean = false` (reflected — enforced via `internals.setValidity()`)
 - `open: boolean = false` (reflected)
+- `size: 'xs' | 's' | 'm' | 'l' | 'xl' = 'm'` (reflected) — visual size; same `xs`–`xl` scale as
+  `<lr-select>`'s own `size`, scaling `[part="trigger"]`/`[part="combobox"]`'s padding/min-height/
+  font-size and `[part="expand-icon"]`'s box size (see the themeable custom properties below).
 - `value: string` — getter/setter (hand-rolled, not the `FormAssociated` mixin); the current model id,
   `''` when nothing is selected. Writing it calls `internals.setFormValue()` synchronously. A named,
   untouched model-select contributes `''` to `FormData` instead of omitting its key.
 
+**Methods:** `click()` (override) — forwards to whichever internal control the active mode renders,
+since `HTMLElement.prototype.click()` is otherwise a no-op on a custom element with no native click
+semantics of its own (mirrors `<lr-button>`'s identical host `click()` forwarding, so a generic
+form-automation helper or another component calling `.click()` on the host actually opens the picker
+instead of silently doing nothing). Closed-dropdown mode forwards a real `.click()` to the trigger
+`<button>`, whose own `@click` handler opens it. Free-text mode instead calls `.focus()` on the
+combobox `<input>`: unlike a genuine pointer click, `HTMLElement.click()` never moves focus (that's a
+`mousedown` side effect the browser applies only to real pointer interaction), and this mode's open
+behavior is wired to the input's `focus` event (`onInputFocus`), not a `click` handler on the input
+itself.
+
 **Mode switching:** `closedMode` (private) is `true` whenever `normalizedCatalog.length > 0 &&
 !allowCustom` — a non-empty `catalog` with `allowCustom` left `false` renders the closed dropdown
 trigger-button UI (`[part="trigger"]`, `role="combobox"` on a `<button>`, no typing). Any other
@@ -10163,10 +11632,21 @@ both modes), `option`, `option-label`, `option-badge` (the "not in catalog" badg
 stale-value row), `expand-icon` (the dropdown chevron, present in both modes), `hint` (the hint
 message), `error` (the error message)
 
-**Themeable custom properties:** shared tokens only — `--lr-space-xs/-s`,
-`--lr-color-border/-surface/-brand/-brand-quiet/-text-quiet`, `--lr-radius`, `--lr-shadow`,
-`--lr-focus-ring-width/-color/-offset`, `--lr-icon-button-size`, `--lr-transition-fast`,
-`--lr-opacity-disabled`.
+**Themeable custom properties:** `--lr-model-select-trigger-padding` (default `var(--lr-space-xs)
+var(--lr-space-s)`) — `[part="trigger"]`/`[part="combobox"]`'s padding shorthand.
+`--lr-model-select-trigger-min-height` (default `var(--lr-size-2-5rem)`) — their block-size floor.
+`--lr-model-select-font-size` (default `var(--lr-font-size-md)`) — their font size.
+`--lr-model-select-expand-size` (default `var(--lr-size-1-75rem)`) — `[part="expand-icon"]`'s
+decorative box size (clamped against `--lr-icon-button-size` via `min()`). All four are declared on
+`:host` at these `size="m"` (the default) values and re-declared inside each
+`:host([size="xs"|"s"|"l"|"xl"])` block at that tier's own value — same xs–xl scale `<lr-select>`
+uses — so `size` is the primary lever; override the cssprop directly only to retune a single tier or
+step outside the scale entirely. `--lr-model-select-option-active-bg` (default
+`var(--lr-color-brand-quiet)`) — background of a hovered or keyboard-active `[part="option"]` row;
+declared as a `var()` fallback at the point of use, not on `:host`, so it isn't tied to `size`. Plus
+shared tokens — `--lr-space-xs/-s`, `--lr-color-border/-surface/-brand/-brand-quiet/-text-quiet`,
+`--lr-radius`, `--lr-shadow`, `--lr-focus-ring-width/-color/-offset`, `--lr-icon-button-size`,
+`--lr-transition-fast`, `--lr-opacity-disabled`.
 
 **Optional peer deps:** none.
 
@@ -10467,11 +11947,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
@@ -10596,7 +12095,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,
@@ -10829,6 +12333,21 @@ for a set rating).
 `commentable` is set), `reasons` (the reason-chip group), `comment` (the comment `<textarea>`), and
 `submit-button`.
 
+**Themeable custom properties:** six pressed-state hooks, three per thumb —
+`--lr-message-feedback-up-active-color` (default `var(--lr-color-success)`),
+`--lr-message-feedback-up-active-bg` (default `var(--lr-color-success-quiet)`),
+`--lr-message-feedback-up-active-border` (default `var(--lr-color-success)`), and the thumbs-down
+trio `--lr-message-feedback-down-active-color`, `--lr-message-feedback-down-active-bg`,
+`--lr-message-feedback-down-active-border` (defaulting to `var(--lr-color-danger)`,
+`var(--lr-color-danger-quiet)`, `var(--lr-color-danger)`). Each styles the glyph, background, and
+border of its thumb only while that thumb is pressed. All six are declared as inline `var()`
+fallbacks at the point of use and never on `:host`, so each can be set on the element *or on any
+ancestor* — a whole transcript's feedback controls retint from one declaration. That shape is
+required because `::part(up-button)[aria-pressed='true']` is invalid CSS (Shadow Parts forbids an
+attribute selector after `::part()`), which previously left overriding the library-wide
+`--lr-color-success`/`--lr-color-danger` tokens as the only lever, repainting every other element
+reading them. Unset, each falls back to exactly the token its rule used before.
+
 ## `lr-push-to-talk`
 
 A mic capture button owning the full `getUserMedia` + `MediaRecorder` lifecycle: permission request,
@@ -10866,7 +12385,14 @@ Blob }`, only when `timeslice-ms > 0`), `lr-record-stop` (`detail: { blob: Blob;
 (visible status text for the `requesting`/`denied`/`error`/unsupported states).
 
 **Themeable custom properties:** `--lr-push-to-talk-size` (default `var(--lr-size-3rem)`) — the
-trigger button's inline and block size.
+trigger button's inline and block size. `--lr-push-to-talk-recording-color` (default
+`var(--lr-color-danger)`) — the border and text color of `[part='trigger']` while `state` is
+`recording`; it recolors only the recording treatment and leaves every other danger-toned surface on
+the page untouched. Like the library's other state hooks it 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(trigger)[data-state='recording']` is invalid CSS (Shadow Parts forbids an attribute selector
+after `::part()`), so re-pointing the shared `--lr-color-danger` token was previously the only way,
+and it repainted every other danger surface with it.
 
 ## `lr-transcript-feed`
 
@@ -10967,6 +12493,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>
@@ -10996,6 +12534,15 @@ string = ''` — accessible name for the group, defaults to the localized `sugge
 **CSS parts:** `base` (the labeled group), `chip` (each suggestion button), `chip-label` (the primary
 text), `chip-detail` (the secondary line, only rendered when `detail` is set).
 
+**Themeable custom properties:** `--lr-suggestion-chips-hover-bg` (default
+`var(--lr-color-brand-quiet)`) — a `chip`'s background on hover. `--lr-suggestion-chips-hover-border`
+(default `var(--lr-color-brand)`) — a `chip`'s border color on hover. Both are declared as `var()`
+fallbacks at the point of use, not on `:host`. Plus shared tokens `--lr-space-xs/-m/-2xs`,
+`--lr-color-border/-surface/-text/-text-quiet`, `--lr-radius-pill`, `--lr-font-size-xs`,
+`--lr-focus-ring-width/-color/-offset`.
+
+**Optional peer deps:** none.
+
 Keyboard: roving tabindex across chips; ArrowLeft/ArrowRight (direction-aware) plus Home/End;
 Enter/Space activate. Renders inside an internal `lr-scroller` (`orientation="horizontal"`,
 `hide-scrollbar`) unless `wrap` is set.
@@ -11039,10 +12586,23 @@ set; `lr-group-toggle` requests the matching state change. `rowActions: ThreadRo
 data mode only: built-in icon buttons rendered into each row's `actions` slot. `showArchived: boolean
 = false` (attribute `show-archived`, reflected) — data mode: include `archived` threads (in their own
 trailing group). `editable: boolean = true` (reflected) — forwarded to each data-mode row's inline
-rename. `label: string = ''` — accessible name for the list region, defaults to the localized
-`threadListLabel`. `wrapRow?: (thread: ChatThread, row: TemplateResult) => TemplateResult` (attribute:
-false) — data mode only: wraps each row's built-in `lr-conversation-item` with host-supplied content
-that has no home in the item's own `title`/`excerpt`/`meta`/`actions` surface (e.g. a leading purpose
+rename. `compact: boolean = false` (reflected) — data mode only: forwarded to each row
+`lr-conversation-item`'s own `compact`, tightening every row's padding and gaps from one attribute
+(the density itself lives on the row item; retune it through
+`--lr-conversation-item-compact-padding`/`-gap` on this element or any ancestor). Slotted mode is a
+deliberate no-op — that mode renders host-supplied items as-is, so the host sets `compact` on its own
+items there, the same division of responsibility slotted mode already has for every other row
+property. `stickyGroups: boolean = false` (attribute `sticky-groups`, reflected) — data mode: pins
+the current date/custom group's header to the top of the scroll viewport while its rows are in view,
+pushing it off as the next group's header arrives. Group headers are ordinary virtualized rows, so
+this renders an `aria-hidden` copy of the header into the internal `lr-virtual-list`'s sticky layer:
+the real row keeps the `role="heading"`/`aria-level` semantics and the tab order (the copy's toggle
+is not a second tab stop), while the pinned copy stays clickable and requests the same
+`lr-group-toggle` collapse. Default `false` renders exactly as before; `grouping="none"` has no
+headers to pin, so it is a no-op there. `label: string = ''` — accessible name for the list region,
+defaults to the localized `threadListLabel`. `wrapRow?: (thread: ChatThread, row: TemplateResult) =>
+TemplateResult` (attribute: false) — data mode only: wraps each row's built-in
+`lr-conversation-item` with host-supplied content that has no home in the item's own `title`/`excerpt`/`meta`/`actions` surface (e.g. a leading purpose
 icon — the item has no default slot to receive one); unset renders the built-in row unwrapped.
 `renderActions?: (thread: ChatThread) => TemplateResult` (attribute: false) — data mode only:
 appends host-supplied content (re-invoked per row on every render, e.g. a `lr-menu` with custom
@@ -11068,20 +12628,67 @@ id }`), `lr-thread-pin` (`detail: { id, pinned }` — the requested new state),
 `lr-thread-rename` (`detail: { id, title }`, re-emitted from the row's `lr-rename`),
 `lr-filter-change` (`detail: { text, matchCount }`), `lr-group-toggle` (`detail: { id, collapsed }` —
 controlled intent; native group buttons provide Enter/Space activation and explicit
-`aria-expanded="true"|"false"`).
+`aria-expanded="true"|"false"`). `searchable` only: `blur`/`focus` (no detail) — re-dispatched from
+the internal search `<input>`'s own `blur`/`focus`, bubbling and composed unlike the native events,
+which are neither.
 
 **CSS parts:** `base`, `search`/`search-input` (the search field wrapper and `<input
 type="search">`), `list` (the list region), `empty`, `viewport` (the actual internal virtual-list
 scroll container, suitable for scrollbar styling), `row-action` (a built-in pin/archive/delete icon
 button), `pin-glyph` (the small pin indicator on a pinned row), `group-header`, `group-toggle`,
-`group-label`, `group-icon`, `row` (all exported across the internal `lr-virtual-list` shadow
-boundary), and `row-leading`/`row-content`/`row-meta`/`row-actions` (the library-owned wrappers around
+`group-label`, `group-icon`, `group-sticky` (`sticky-groups` only: the pinned copy of the current
+group's header, exported from the internal `lr-virtual-list`'s sticky layer — it wraps a full copy of
+the `group-header`/`group-toggle`/`group-label`/`group-icon` markup, so those parts style the real
+header row and the pinned copy alike, and the band itself is where a shadow or bottom border
+belongs), `row` (all exported across the internal `lr-virtual-list` shadow
+boundary), `row-wrapper` (the wrapper around `wrapRow` output, only present when `wrapRow` is set;
+row-only — group headers are never passed through `wrapRow`, so they never carry it), and
+`row-leading`/`row-content`/`row-meta`/`row-actions` (the library-owned wrappers around
 their corresponding render-hook output; inherited fonts, layout values, and theme custom properties
 reach callback-rendered descendants through these parts).
 
+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`,
+`row-item-title`, `row-item-title-input`, `row-item-rename-button`, `row-item-excerpt`,
+`row-item-meta`, `row-item-timestamp`, `row-item-actions`.
+
+**Keep the two prefixes straight — they are different surfaces.** The `row-*` parts wrap *this*
+component's own render-callback output (`wrapRow`, `renderLeading`, `renderRowContent`,
+`renderMeta`, `renderActions`); the `row-item-*` parts are the row item's *internals*. Row density
+in particular lives in `row-item-base`'s padding and `row-item-title`'s font size, so
+`::part(row-item-base)` is the supported way to build a dense sidebar.
+
+For plain row density, prefer the `compact` property above — it forwards straight to the row item's
+own density knob. The `row-item-*` parts remain the lever for tuning beyond it (a different font
+size, a different padding ratio):
+
+```css
+lr-thread-list::part(row-item-base) { padding-block: 0.25rem; }
+lr-thread-list::part(row-item-title) { font-size: 0.8125rem; }
+```
+
+Do **not** reach for `::part(row) { --lr-theme-space-s: … }` instead. That is a whole-subtree
+retheme: it shrinks everything nested inside the row, including the items of a `renderActions` menu,
+which pushes their touch targets below the accessible minimum. The `row-item-*` parts exist so row
+density can be tuned without that blast radius.
+
+**Sizing:** the internal list fills whatever height this component is given, with no consumer CSS —
+`[part='viewport']` is the real scroll container, and it falls back to `lr-virtual-list`'s own `24rem`
+default only when the container has no resolvable height. This is deliberately *not* implemented by
+setting `--lr-virtual-list-height: 100%`: that percentage resolves against this host, which is a flex
+item, so in an auto-height container it chains to `auto` and the viewport either collapses to zero
+(with no rows) or grows to the full un-virtualized content height (with rows) — defeating
+virtualization in both directions. Instead the list host is made a column flex container, which turns
+the shipped `24rem` into a *flex-basis*: it grows to fill a bounded pane, shrinks below `24rem` in a
+short one, and falls back to exactly `24rem` in an auto-height container.
+
+`sticky-groups` keeps the current date group's header visible while scrolling through a long sidebar;
+style the pinned band with `lr-thread-list::part(group-sticky)`.
+
 ```html
 <lr-thread-list
   searchable
+  sticky-groups
   .threads=${threads}
   active-id=${activeThreadId}
   .rowActions=${['pin', 'archive', 'delete']}
@@ -11262,6 +12869,14 @@ identically-named properties.
 getter/setter (the current voice id, `''` when nothing is selected), `name` (reflected), `disabled`
 (reflected), `required` (reflected — enforced via `internals.setValidity()`).
 
+**Methods:** `click()` (override) — same forwarding contract as `lr-model-select`'s own `click()`
+override (see that section for the full rationale): closed-dropdown mode forwards a real `.click()`
+to the trigger `<button>`, whose own `@click` handler opens it; free-text mode instead calls
+`.focus()` on the combobox `<input>`, since a synthetic `.click()` on a text input never dispatches
+`focus` the way a real click's `mousedown` default action does, and this mode's open behavior is
+wired to the input's native `focus` event, not a `click` handler on the input itself. Mirrors
+`<lr-button>`'s identical host `click()` forwarding.
+
 **Events:** `lr-change` — `detail: { value, inCatalog }`. `lr-preview-request` — `detail: {
 voiceId, previewUrl? }`, cancelable. `lr-preview-change` — `detail: { voiceId }`, internal playback
 started (`voiceId`) or stopped (`null`). Plus mirrored native `input`/`change` and re-dispatched
@@ -11945,6 +13560,11 @@ invention (no Web Awesome equivalent).
 - `maxHeight: string = ''` (attribute: `max-height`) — caps the rendered block size and enables an
   internal scrollbar once content exceeds it (any valid CSS length). Empty string (the default)
   grows with content.
+- `appearance: 'card' | 'plain' = 'card'` (reflected) — visual chrome, mirroring `lr-card`'s
+  `appearance` vocabulary. `'card'` keeps the bordered, filled, padded box. `'plain'` removes the
+  border, background, padding and corner radius, so a trace nested inside an
+  `lr-result-card`/`lr-agent-run` — which already draws a border — doesn't double the frame. The
+  `max-height` scroll cap and the copy/frame affordances are unaffected either way.
 
 **Events:**
 - `lr-frame-select` (`detail: { file?: string; line?: number; column?: number; raw: string }`) —
@@ -11955,7 +13575,8 @@ invention (no Web Awesome equivalent).
 
 **Slots:** none.
 
-**CSS parts:** `base` (the root wrapper; respects `max-height`), `message` (the leading error
+**CSS parts:** `base` (the root wrapper; respects `max-height`, and drops its card chrome under
+`appearance="plain"`), `message` (the leading error
 message text for a group), `group` (one chained-error group of frames), `frame` (a single frame
 button; carries `data-internal` for internal frames), `frame-function` (the frame's function
 name), `frame-location` (the frame's `file:line:col` text), `internal-toggle` (the collapse/expand
@@ -12014,6 +13635,10 @@ renders at the start of the action row, before Deny/Edit/Approve.
 **Properties:**
 - `open: boolean = false` (reflected) — set this (or call `close()`) to dismiss; there is no separate
   `show()`/`hide()` pair
+- `accessibleLabel: string | null = null` (attribute `aria-label`) — directly names the internal
+  dialog panel; otherwise the tool-name heading supplies `aria-labelledby`. Mirrors
+  `<lr-tool-result-dialog>`'s/`<lr-tool-select-dialog>`'s own host-`aria-label` override pattern; fed
+  only by a host `aria-label`
 - `toolName: string = ''` (attribute `tool-name`) — the proposed call's name, e.g. `web_search`;
   drives the heading and the dialog's accessible name
 - `args: unknown = {}` (attribute: false) — the proposed call's arguments, rendered via
@@ -12026,11 +13651,7 @@ renders at the start of the action row, before Deny/Edit/Approve.
   `autoCorrect: string = 'off'` (attribute `autocorrect`), `autocomplete: string = 'off'`,
   `wrap: 'hard'|'soft'|'off' = 'soft'`, `inputMode: string = ''` (attribute `inputmode`),
   and `enterKeyHint: string = ''` (attribute `enterkeyhint`) — forwarded to the raw-JSON
-  textarea; the defaults keep browser editing assistance from changing JSON text
-- `spellcheck: boolean = false`, `autocapitalize: string = 'off'`, `autoCorrect: string = 'off'`
-  (`autocorrect`), `autocomplete: string = 'off'`, `wrap: 'hard'|'soft'|'off' = 'soft'`,
-  `inputMode: string = ''` (`inputmode`), and `enterKeyHint: string = ''` (`enterkeyhint`) —
-  forwarded to the raw-JSON `<textarea>` while editing.
+  `<textarea>` while editing; the defaults keep browser editing assistance from changing JSON text
 
 **Methods:** `close(reason: ToolApprovalDialogCloseReason = 'api'): void` — closes the dialog, emits
 `lr-close` with `reason`, and returns focus to whatever had it before the dialog opened; a no-op if
@@ -12265,6 +13886,15 @@ A small bordered card shell. Purely visual, with no state of its own beyond slot
 **Properties:**
 - `title: string = ''` — small heading for the card. Leave unset for an untitled card (e.g. a bare
   block of `lr-result-field` rows with no natural heading).
+- `compact: boolean = false` (reflected) — tighter header/body padding for dense contexts (a card
+  rendered as a row in a transcript or result list), same convention as `<lr-agent-run>`'s own
+  `compact`. Purely a density knob: the border and background stay, so use `appearance="plain"`
+  instead to drop the chrome entirely.
+- `appearance: 'card' | 'plain' = 'card'` (reflected) — mirrors `lr-card`'s/`<lr-agent-run>`'s
+  `appearance` vocabulary. `'card'` (the default) keeps the bordered, filled box. `'plain'` removes
+  the border, background, and corner radius, so a card nested inside a host frame that already draws
+  a border (e.g. `<lr-tool-result-view>`'s own chrome) doesn't double it. `plain` wins over `compact`
+  when both are set (nothing left to tighten).
 
 **Events:** none.
 
@@ -12279,8 +13909,11 @@ later `slotchange` on `actions` is still observed, but `hidden` whenever there's
 default tooltip, scoped to just this element rather than the whole card), `actions` (`hidden`
 whenever the slot has no assigned content), `body`.
 
-**Themeable custom properties:** shared tokens only — `--lr-space-xs`/`-s`, `--lr-color-border`/
-`-surface`/`-text`, `--lr-radius`.
+**Themeable custom properties:** `--lr-result-card-compact-header-padding` (default
+`var(--lr-space-xs)`) — `[part="header"]` block/inline padding while `compact`;
+`--lr-result-card-compact-body-padding` (default `var(--lr-space-xs)`) — `[part="body"]` padding
+while `compact`; plus shared tokens — `--lr-space-xs`/`-s`, `--lr-color-border`/`-surface`/`-text`,
+`--lr-radius`.
 
 ### `lr-result-field`
 
@@ -12380,9 +14013,19 @@ Space).
 bar), `meta` (secondary row info, shown inline under 480px), `status-text`, `duration`, `empty` (shown
 when `spans` is empty), and `live-region`.
 
-**Themeable custom properties:** `--lr-span-waterfall-name-width` (default `8rem`) and
+**Themeable custom properties:** `--lr-span-waterfall-name-width` (default `8rem`),
 `--lr-span-waterfall-stripe-speed` (a `running` span's striped-bar animation duration; defaults to
-`--lr-transition-ambient`).
+`--lr-transition-ambient`), and `--lr-span-waterfall-row-active-bg` (default
+`var(--lr-color-brand-quiet)`) — the background of the active (`activeSpanId`) row.
+
+That last one follows the convention every **state-scoped** custom property in this family uses, and
+it is worth reading once: it is an inline `var()` fallback at its point of use and is deliberately
+**not** declared on `:host`, so it can be set on the element *or on any ancestor* and still reach the
+rule that consumes it. It exists because Shadow Parts forbids an attribute selector after `::part()`
+— `::part(row)[data-active]` and every selector like it is invalid CSS — so before it, the only way
+to restyle a state-dependent surface was to override a library-wide `--lr-color-*` token, which repaints
+every other surface reading that token. Every `*-active-*`, `*-selected-*` and per-state color
+property below works the same way.
 
 ## `lr-task-list`
 
@@ -12397,7 +14040,13 @@ status: TaskStatus; detail?: string; children?: TaskItem[] }` with `TaskStatus =
 'running' | 'success' | 'error'` (both exported here). `detail` is an optional secondary plain-text
 line; `children` is exactly **one** level of sub-steps — a child's own `children` is ignored with a
 `console.warn`. `label: string = 'Tasks'`, `expanded: boolean = true` (reflected), and
-`collapsible: boolean = true`.
+`collapsible: boolean = true`. `compact: boolean = false` (reflected) — tighter header/body padding
+and item gap for dense contexts (a plan tracker nested in an already-padded transcript row), same
+convention as `<lr-agent-run>`'s/`<lr-source-card>`'s `compact`; purely a density knob, the border
+and background stay. `appearance: 'card' | 'plain' = 'card'` (reflected) — mirrors `lr-card`'s
+`appearance` vocabulary; `'plain'` removes `[part="base"]`'s border, background, and corner radius so
+a list embedded in a frame that already draws a border (an agent-run panel, a message bubble) doesn't
+double it.
 
 **Slots:** `detail-<id>` — dynamic, one per item id (e.g. `slot="detail-step-3"`); rich detail under
 that item's label, typically a `<lr-tool-call-chip>` or file `<lr-chip>`.
@@ -12413,7 +14062,11 @@ indicator, only rendered when `collapsible`), `body` (the list of items, `hidden
 children).
 
 **Themeable custom properties:** `--lr-task-list-spin` (default `1s linear`) — running-status icon
-spin animation duration/timing.
+spin animation duration/timing; `--lr-task-list-compact-header-padding` (default
+`var(--lr-space-2xs) var(--lr-space-s)`) — `[part="header"]` padding while `compact`;
+`--lr-task-list-compact-gap` (default `var(--lr-space-2xs)`) — gap between `[part="body"]`'s item
+rows while `compact`; `--lr-task-list-compact-body-padding` (default `var(--lr-space-2xs)
+var(--lr-space-s) var(--lr-space-s)`) — `[part="body"]` padding while `compact`.
 
 ## `lr-terminal`
 
@@ -12441,12 +14094,24 @@ text, anchor, rects }`).
 
 **CSS parts:** `base`, `toolbar` (only rendered when copy/download are enabled), `copy-button`,
 `download-button`, `viewport` (the `role="log"` scrollable region), `line` (one rendered line; carries
-`data-line-number`/`data-match`/`data-highlight-tone`), `jump-to-latest` (shown while `follow` is
+`data-line-number`/`data-match`/`data-highlight-tone`, and is forwarded via `exportparts` so
+`lr-terminal::part(line)` reaches the rendered lines from a consumer stylesheet despite them living
+in the internal `<lr-virtual-list>`'s shadow root), `jump-to-latest` (shown while `follow` is
 disengaged and new output has arrived), and `announcer` (the visually-hidden `role="status"` region
 used when `announce-output` is set).
 
 **Themeable custom properties:** `--lr-terminal-height` (default `var(--lr-size-20rem)`) — the
-viewport's block size.
+viewport's block size; not declared on `:host`, so it is inherited from the host or any ancestor.
+`--lr-terminal-highlight-accent-bg` (default `var(--lr-color-brand-quiet)`),
+`--lr-terminal-highlight-success-bg` (default `var(--lr-color-success-quiet)`),
+`--lr-terminal-highlight-warning-bg` (default `var(--lr-color-warning-quiet)`),
+`--lr-terminal-highlight-danger-bg` (default `var(--lr-color-danger-quiet)`), and
+`--lr-terminal-highlight-neutral-bg` (default `var(--lr-color-surface)`) — the background of a
+`highlights[]` entry of the matching `tone`. Each is decoupled from the identical shared token it
+falls back to (e.g. `accent`'s `--lr-color-brand-quiet` is also the copy/download-button hover tint)
+so retinting one tone doesn't repaint the other surface reading that token, and from any
+`::part('line')` stylesheet override — the background is applied inline, so a stylesheet rule can't
+beat it without `!important`.
 
 ## `lr-trace-tree`
 
@@ -12472,6 +14137,29 @@ as a root rather than being dropped. `activeSpanId: string | null = null`
 `duration`, `tokens-in`, `tokens-out` (when `showTokens`), `cost` (when `showCost`), `bar-track`,
 `bar`, `empty` (shown when `spans` is empty), and `live-region`.
 
+**Themeable custom properties:** `--lr-trace-tree-row-active-bg` (default
+`var(--lr-color-brand-quiet)`) — the background of the active (`activeSpanId`) row — and
+`--lr-trace-tree-row-active-color` (default `var(--lr-color-text)`) — the color of that row's
+secondary text (`detail`, `duration`, `tokens-in`, `tokens-out`, `cost`, and the `pending`
+`status-text` label). Same state-scoped-property convention described under `lr-span-waterfall`
+above: an inline `var()` fallback rather than a `:host` declaration, so either can be set on the
+element or any ancestor, and they exist because `::part(row)[data-active]` is invalid CSS.
+
+**Contrast note:** the active row is more than a tint. Its secondary text would sit at ~4.25:1
+against the default tint if it stayed at `--lr-color-text-quiet`, so it rises to full-strength
+`--lr-color-text` while the row is active, and the semantic `status-text` labels are rendered as
+`color-mix(in srgb, var(--lr-color-<tone>) 75%, var(--lr-color-text))` — keeping the status hue
+(an error row stays red) while clearing the 4.5:1 floor (success 4.46 → 6.18, `denied` 4.28 →
+5.96). Both adjustments are theme-symmetric, because `--lr-color-text` flips with the color
+scheme. `[part='bar']` is deliberately untouched: it is a non-text graphic on a 3:1 floor, and its
+saturation is the row's primary status signal.
+
+The two properties are a **pair**. The defaults assume the active background stays on the same
+side of the lightness midpoint as the ambient surface, so a consumer who sets
+`--lr-trace-tree-row-active-bg` to a dark tint in light mode (or a light one in dark mode) must
+set `--lr-trace-tree-row-active-color` to match, and should re-check the status-label tones
+against the new tint as well.
+
 ## `lr-activity-feed`
 
 An append-only streaming log of granular agent actions ("Searching the web…", "Read
@@ -12500,12 +14188,21 @@ rather than augmenting it, and `virtualizeThreshold: number = 200` (attribute
 
 **CSS parts:** `base`, `header` (a `<button>`), `status-dot` (pulses while `mode="live"`),
 `summary`, `toggle`, `body` (the scrollable region, or the internal virtual-list), `entry` (carries
-`data-tone`), `entry-icon`, `entry-text`, and `entry-timestamp` (only while `showTimestamps` and a
-valid `timestamp` is set).
+`data-tone`), `entry-icon`, `tone-dot` (the dot rendered inside `entry-icon` when the entry sets no
+literal `icon`), `tone-dot-neutral`/`tone-dot-brand`/`tone-dot-success`/`tone-dot-warning`/
+`tone-dot-danger` (each also carries `tone-dot`), `entry-text`, and `entry-timestamp` (only while
+`showTimestamps` and a valid `timestamp` is set). Every entry-level part is reachable in both
+rendering paths, virtualized or not.
 
 **Themeable custom properties:** `--lr-activity-feed-max-height` (default `16rem`) — cap on how
 tall the expanded body grows before it scrolls internally.
 
+**Known gotchas:**
+- The tone dot's color is selected by its *part name*, not by `[data-tone]`: `::part()` cannot be
+  followed by an attribute selector, so `lr-activity-feed::part(tone-dot)[data-tone='success']`
+  never matches. Target `lr-activity-feed::part(tone-dot-success)` instead. `data-tone` remains on
+  both the entry and the dot for DOM queries.
+
 ## `lr-commit-card`
 
 A compact commit summary (subject, author/time, diffstat, per-file changes) that links file rows out
@@ -12518,6 +14215,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).
 
@@ -12528,6 +14232,9 @@ boolean = true` (attribute `files-collapsed`, reflected), and `copyable: boolean
 `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`.
+
 ## `lr-test-results`
 
 A pass/fail suite summary with per-status counts, status filter toggles, and per-test rows whose
@@ -12555,6 +14262,17 @@ expanded/collapsed).
 `data-status`), `test-status`, `test-name`, `test-duration`, `test-expand-toggle`, `failure`
 (hidden while collapsed), and `failure-message`.
 
+**Themeable custom properties:** `--lr-test-results-filter-active-bg` (default
+`var(--lr-color-brand-quiet)`), `--lr-test-results-filter-active-border` (default
+`var(--lr-color-brand)`) and `--lr-test-results-filter-active-color` (default
+`var(--lr-color-brand)`) — the background, border color and text color of a pressed (active) status
+filter toggle. All three follow the state-scoped-property convention described under
+`lr-span-waterfall`: inline `var()` fallbacks rather than `:host` declarations, so each can be set on
+the element or on any ancestor. They exist because
+`::part(filter-toggle)[aria-pressed='true']` is invalid CSS — Shadow Parts forbids an attribute
+selector after `::part()` — so restyling the pressed state otherwise meant overriding the
+library-wide brand tokens.
+
 ## `lr-confirm-bar`
 
 An inline, non-modal approve/deny block for one proposed action — the in-flow sibling of
@@ -12572,7 +14290,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.
@@ -12585,6 +14310,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}
@@ -12667,12 +14410,22 @@ src? }`, with the sanitized download URL).
 
 **CSS parts:** `base`, `header`, `label`, `kind`, `view-toggle` (rendered only once the `code` slot
 has content), `view-button` (carries `data-view="preview"` or `data-view="code"`), `version-nav`
-(rendered only once `versions` is non-empty), `version-previous`, `version-next`, `version-position`
+(rendered only once `versions` is non-empty), `version-previous`, `version-previous-glyph` (the `‹`
+chevron inside `version-previous`, mirrored via `scaleX(-1)` under `:dir(rtl)`), `version-next`,
+`version-next-glyph` (the `›` chevron inside `version-next`, mirrored the same way), `version-position`
 (the "Version N of M" text), `restore-button` (rendered only while the active version isn't the
 latest), `actions`, `copy-button` (rendered only while `copyText` is non-empty), `download-button`
 (rendered only while `downloadSrc` is non-empty), `body`, `streaming-indicator` (rendered only while
 `streaming`).
 
+**Themeable custom properties:** `--lr-artifact-panel-view-active-bg` (default
+`var(--lr-color-brand-quiet)`) and `--lr-artifact-panel-view-active-color` (default
+`var(--lr-color-brand)`) — the background and text color of the pressed (active) preview/code toggle
+button. Both follow the state-scoped-property convention described under `lr-span-waterfall`: inline
+`var()` fallbacks rather than `:host` declarations, so either can be set on the element or on any
+ancestor. They exist because `::part(view-button)[aria-pressed='true']` is invalid CSS, leaving the
+library-wide brand tokens as the only prior lever.
+
 ```html
 <lr-artifact-panel label="report.md" kind="document" .versions=${versions}
   @lr-restore=${(e) => restoreVersion(e.detail.versionId)}>
@@ -12718,6 +14471,16 @@ cancelable. Retry is available for `error` and `cancelled`.
   `show-retry`) — whether the built-in buttons may render at all, still gated by the run's own
   status. Both use a `true`-defaulting string converter, so plain-HTML `show-cancel="false"` works; a
   `?show-cancel=${false}` boolean-attribute binding starting from absent markup does not
+- `compact: boolean = false` (reflected) — tighter root padding and header/body gap for dense
+  contexts (a run rendered as a row in a list, or in a side panel); same convention as `lr-empty`'s
+  `compact`. Purely a density knob: the border and background stay, so reach for
+  `appearance="plain"` instead when the goal is to drop the chrome entirely
+- `appearance: 'card' | 'plain' = 'card'` (reflected) — visual chrome, mirroring `lr-card`'s
+  `appearance` vocabulary. `'card'` keeps the bordered, filled, padded box; `'plain'` removes the
+  border, background, padding and corner radius, so a run nested inside a host frame that already
+  draws a border doesn't double it. `plain` wins over `compact` when both are set — there is no
+  padding left to tighten. The built-in Cancel/Retry buttons draw their own border and background
+  and stay visibly interactive either way
 
 **Events:** `lr-cancel` (`detail: CancelEventDetail` = `{ reason?: string }`, from
 `@aceshooting/lyra-ui/ai`; `reason` is `undefined` from the built-in button), `lr-retry`
@@ -12734,7 +14497,12 @@ this component's own retry counter, reset when `run.id` changes).
 (carries `data-variant`), `empty`.
 
 **Themeable custom properties:** `--lr-agent-run-spin` (default `1s linear`) — the running-status
-spinner icon's rotation duration/timing.
+spinner icon's rotation duration/timing. `--lr-agent-run-compact-padding` (default
+`var(--lr-space-s)`) and `--lr-agent-run-compact-gap` (default `var(--lr-space-s)`) — `[part="base"]`'s
+padding, and the gap between its header and body, while `compact`; both are ignored while `compact`
+is unset. Like the other density/state properties in this family they are inline `var()` fallbacks at
+their point of use rather than `:host` declarations, so either can be set on the element *or on any
+ancestor* — one rule on a run list retunes every compact run inside it.
 
 ## `lr-agent-trace`
 
@@ -12767,6 +14535,17 @@ graph node-type ids).
 visible span has `kind: 'agent'`), `handoff` (one entry — a `<button>` wrapping an
 `lr-handoff-divider`, carrying `data-active`), `tree` (the composed `lr-trace-tree`).
 
+**Themeable custom properties:** `--lr-agent-trace-handoff-active-bg` (default
+`var(--lr-color-brand-quiet)`) — the background of the active (`activeSpanId`) handoff quick-jump
+entry. Same state-scoped-property convention described under `lr-span-waterfall`: an inline `var()`
+fallback rather than a `:host` declaration, settable on the element or any ancestor, and it exists
+because `::part(handoff)[data-active]` is invalid CSS. The composed tree's own
+`--lr-trace-tree-row-active-bg` and `--lr-trace-tree-row-active-color` are separate knobs and
+inherit straight through, so restyling both surfaces means setting both — and they carry the
+pairing caveat documented under `lr-trace-tree` above: the tree's active-row defaults assume the
+active background stays on the same side of the lightness midpoint as the ambient surface, so a
+tint that crosses it needs the matching text color set too.
+
 ## `lr-context-inspector`
 
 Inspection view of model-call context segments, with token estimates, source citations, redaction
@@ -12830,7 +14609,9 @@ Filterable and taggable evaluation-example list with add, remove, import, and ex
 
 **Events:** `lr-example-select` (`detail: { id: string | null }`), `lr-example-add-request`
 (`detail: undefined`), `lr-example-remove-request` (`detail: { id: string }`), `lr-import-request`
-(`detail: { files: File[] }`), `lr-export-request` (`detail: { format: string }`).
+(`detail: { files: File[] }`), `lr-export-request` (`detail: { format: string }`). `focus`/`blur` —
+re-dispatched (no detail) when the internal search field (only rendered while `searchable`) gains or
+loses focus, since native focus neither bubbles nor crosses the shadow boundary.
 
 **CSS parts:** `base`, `toolbar`, `search`, `search-input`, `tag-filter`, `grid`,
 `add-button`, `remove-button`, `import`, `export`.
@@ -12935,6 +14716,16 @@ gate.
 **CSS parts:** `base`, `empty`, `summary`, `count`, `state-badge`,
 `list`, `decision`, `decision-header`, `category`, `label`, `detail`, `explanation`.
 
+**Themeable custom properties:** `--lr-policy-summary-count-allow-color` (default
+`var(--lr-color-success)`), `--lr-policy-summary-count-deny-color` (default
+`var(--lr-color-danger)`) and `--lr-policy-summary-count-needs-review-color` (default
+`var(--lr-color-warning)`) — the text color of each state's count in the summary strip. All three
+follow the state-scoped-property convention described under `lr-span-waterfall`: inline `var()`
+fallbacks rather than `:host` declarations, so each can be set on the element or on any ancestor.
+They exist because `::part(count)[data-state='deny']` is invalid CSS — Shadow Parts forbids an
+attribute selector after `::part()` — so retoning one state's count otherwise meant overriding the
+library-wide status tokens and repainting every other surface reading them.
+
 ## `lr-tool-timeline`
 
 Chronological list of agent tool/function calls composed from tool-call, result, and approval
@@ -12978,7 +14769,12 @@ can ignore it; one actually executing the tool needs it.
 
 **Themeable custom properties:** `--lr-tool-timeline-gap` (default `var(--lr-space-l)`) — vertical
 gap between entries; `--lr-tool-timeline-marker-size` (default `var(--lr-size-0-625rem)`) — the
-per-entry timeline marker dot's size, which also sets the entry grid's leading column width.
+per-entry timeline marker dot's size, which also sets the entry grid's leading column width;
+`--lr-tool-timeline-denied-marker-color` (default `var(--lr-color-warning)`) — rail-dot color for a
+`status="denied"` entry, decoupled from the pending-approval border color below so either can be
+retinted independently; `--lr-tool-timeline-pending-approval-border-color` (default
+`var(--lr-color-warning)`) — color of the entry body's leading border while that entry's
+`data-pending-approval` is `"true"`.
 
 # Retrieval, knowledge graph & grounding (`components/retrieval/`)
 
@@ -13074,7 +14870,10 @@ Enter/Space activations within 500ms — regardless of `GraphNode.expandable`),
 `label`, `link-label` (a drawn edge label, only rendered when `showEdgeLabels` is set),
 `expand-indicator` (the "+" badge on a node with `expandable: true`), `focus-halo` (the persistent
 ring tracking `focusId`'s node), `hull` (a community hull), `community-label`,
-`live-region`, `data-list`, `empty`, `canvas`/`tooltip`/`cursor-items`/`cursor-item`
+`live-region`, `data-list`, `empty`, `error` (`role="alert"` message shown instead of the graph when
+the optional `d3-force`/`d3-drag`/`d3-zoom`/`d3-selection` peers fail to load —
+distinct from the empty state, which means the peers loaded fine but `nodes` is empty),
+`canvas`/`tooltip`/`cursor-items`/`cursor-item`
 (`renderer="canvas"` only — the drawing surface, its hover tooltip replacing the SVG `<title>`, and
 the offscreen keyboard-roving items)
 
@@ -13215,7 +15014,9 @@ with a `droppable` canvas on the `FLOW_PALETTE_MIME_TYPE` drag payload shape.
 
 **Events:** `lr-palette-place` (`detail: { type }`, a pointer click or Enter/Space — the
 click/keyboard alternative to dragging), `lr-select` (`detail: { item }`, emitted alongside
-`lr-palette-place` on both gestures, carrying the full item).
+`lr-palette-place` on both gestures, carrying the full item), `focus`/`blur` (no detail —
+re-dispatched from the internal search field's own `focus`/`blur`, bubbling and composed unlike
+the native events, since neither bubbles nor crosses the shadow boundary on its own).
 
 **Slots:** `header` (content above the search field, e.g. a heading or tabs), `footer` (content
 below the list).
@@ -13278,7 +15079,10 @@ after each toggle).
 **CSS parts:** `base`, `item` (a `<button>` when `interactive`, a plain `<div>` otherwise), `swatch`,
 `label`, `count`, `live-region` (the visually hidden filter-toggle announcement).
 
-**Themeable custom properties:** no component-local tokens; reads `--lr-graph-cat-1` through `-8`
+**Themeable custom properties:** `--lr-graph-legend-hidden-color` (default
+`var(--lr-color-text-quiet)`) — text color of a filtered-out (hidden) row's `label`/`count`,
+independent of the shared quiet-text token so a host can retint "hidden" rows without repainting
+every other quiet-text surface. Also reads `--lr-graph-cat-1` through `-8`
 (the same computed-style fallback palette `lr-graph`/`lr-word-cloud` use) plus shared tokens.
 
 **Optional peer deps:** none.
@@ -13321,6 +15125,15 @@ itself — `lr-entity-activate` is a request a host routes into `lr-graph`'s own
   `lr-graph-legend.types` entry shape, resolving `entity.type` to a label/color/shape for the badge
 - `communityLabel: string = ''` (attribute `community-label`) — override text for the community chip
 - `showFocusButton: boolean = true` (attribute `show-focus-button`)
+- `compact: boolean = false` (reflected) — tighter root padding and row gap for dense contexts (a
+  dossier rendered in a sidebar, a result list) — the same convention as `lr-empty`'s `compact` and
+  as this component's sibling `lr-community-card`. Purely a density knob: the border and background
+  stay. `false` (the default) keeps the full card padding.
+- `appearance: 'card' | 'plain' = 'card'` (reflected) — visual chrome, mirroring `lr-card`'s
+  `appearance` vocabulary. `'card'` (the default) keeps the bordered, filled, padded box; `'plain'`
+  removes the border, background, padding and corner radius, so a card nested inside a container
+  that already draws a border doesn't double the frame. `plain` wins over `compact` when both are
+  set — there is nothing left to tighten.
 
 **Events:** `lr-entity-activate` (`detail: { id }`, the built-in focus button was activated).
 
@@ -13331,7 +15144,11 @@ itself — `lr-entity-activate` is a request a host routes into `lr-graph`'s own
 `description`, `properties`, `property` (one key/value row), `degree`, `community`, `actions`,
 `focus-button`, `empty` (shown when `entity` is `null`).
 
-**Themeable custom properties:** shared tokens only; a data-driven `entity.type` color is applied as
+**Themeable custom properties:** `--lr-entity-card-compact-padding` (default `var(--lr-space-s)`) —
+`[part='base']`'s padding while `compact`; `--lr-entity-card-compact-gap` (default
+`var(--lr-space-xs)`) — the gap between `[part='base']`'s rows while `compact`. Both apply only in
+the `compact` state, so a dense card can be tuned without re-pointing shared spacing tokens for
+everything else. Otherwise shared tokens; a data-driven `entity.type` color is applied as
 sanitized inline `--lr-badge-*` overrides on the type badge only (the one "type color is
 data-driven by design" exception this library already grants graph nodes) — every other color comes
 from tokens.
@@ -13417,10 +15234,13 @@ name and detail shape as `lr-graph`'s own event, so one host handler serves both
 
 **Slots:** none.
 
-**CSS parts:** `base` (`role="list"`), `group-header` (only when `groupByRelation`), `row`
-(`role="listitem"`), `direction` (`aria-hidden` glyph), `relation`, `node-label`, `node-meta`
-(secondary type/degree text, when present), `expand-button` (only when `expandable`), `empty`
-(shown when `rows` is empty).
+**CSS parts:** `base` (`role="list"`), `group-header` (only when `groupByRelation`; above
+`virtualizeAt` this is the internal virtual-list's own group label, re-exported under the same
+name), `row` (`role="listitem"`; above `virtualizeAt` this is the internal virtual-list's own row
+wrapper, re-exported under the same name), `direction` (`aria-hidden` glyph), `relation`,
+`node-label`, `node-meta` (secondary type/degree text, when present), `expand-button` (only when
+`expandable`), `empty` (shown when `rows` is empty). Every part presents identically either side of
+`virtualizeAt`.
 
 **Themeable custom properties:** shared tokens only.
 
@@ -13438,6 +15258,9 @@ name and detail shape as `lr-graph`'s own event, so one host handler serves both
 **Known gotchas:**
 - `lr-node-expand`'s detail shape is intentionally identical to `lr-graph`'s own event of the
   same name, so a single listener wired to both handles "expand this node's neighborhood" uniformly.
+- A row is exactly one `[part="row"]` element in both rendering paths. Above `virtualizeAt` that
+  element is the internal virtual-list's own row wrapper (the component renders only the row's
+  content into it), so a `::part(row)` rule applies once, not twice.
 
 ---
 
@@ -13499,6 +15322,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
@@ -13555,13 +15383,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.
 
@@ -13614,7 +15470,19 @@ fired after every toggle including select-all).
 `lr-file-icon` type badge), `label`, `empty` (`noData` when `sources` is empty, `noMatches` when a
 filter empties the tree).
 
-**Themeable custom properties:** shared tokens only.
+**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
+a fully-selected entry's `[part='checkbox']` (whose resting default is `var(--lr-color-brand)`). The
+two keep their distinct defaults while it is unset; setting it unifies both.
+`--lr-source-picker-checked-border` (default `var(--lr-color-brand)`) — the border color of every
+checked *or* mixed selection control. `--lr-source-picker-mixed-bg` (default
+`color-mix(in srgb, var(--lr-color-brand) 50%, var(--lr-color-surface))`) — the background of a
+partially-selected entry's `[part='checkbox']`, so a tri-state folder reads as distinct from a fully
+selected one. All three are inline `var()` fallbacks at the point of use rather than `:host`
+declarations, so each can be set on the element *or on any ancestor*:
+`::part(checkbox)[aria-checked='true']` is invalid CSS — Shadow Parts forbids an attribute selector
+after `::part()` — which previously left re-pointing the library-wide `--lr-color-brand` token as
+the only lever, repainting every other brand surface with it. Plus shared tokens otherwise.
 
 **Optional peer deps:** none.
 
@@ -13709,7 +15577,9 @@ keyboard descent).
 announcement region), `empty` (shown when `topics` is empty).
 
 **Themeable custom properties:** `--lr-mind-map-ring-gap` (default `6rem`, radius step per depth
-ring).
+ring). `--lr-mind-map-node-hover-halo` (default `var(--lr-color-brand-quiet)`) — stroke color of
+the halo drawn around a topic node's dot on `:hover`, giving mouse users the same "this is
+clickable" feedback keyboard users already get from the drawn `focus-ring` part.
 
 **Optional peer deps:** none.
 
@@ -13873,6 +15743,15 @@ while collapsed).
 - `page?: string | number` — optional page reference, e.g. `12` or `"iv"`, rendered as-is (never
   parsed/validated as a number), appended to the title as `" — p. {page}"`.
 - `href?: string` — optional URL, echoed back (unopened) in `lr-open`'s detail.
+- `compact: boolean = false` (reflected) — tighter root padding and row gap, for the dense citation
+  lists these cards usually render in — the same convention as `lr-empty`'s `compact`. Purely a
+  density knob: the border and background stay. `false` (the default) keeps the full card padding.
+- `appearance: 'card' | 'plain' = 'card'` (reflected) — visual chrome, mirroring `lr-card`'s
+  `appearance` vocabulary. `'card'` (the default) keeps the bordered, filled, padded box; `'plain'`
+  removes the border, background, padding and corner radius, so a card inside a `<lr-source-list>`
+  (or any container already drawing its own border/dividers) doesn't double the frame. `plain` wins
+  over `compact` when both are set — nothing left to tighten. The title and toggle keep their brand
+  color and hover underline under `plain`, since neither ever depended on the card chrome.
 
 **Events:**
 - `lr-expand` (`detail: { sourceId: string; expanded: boolean }`) — the per-card "Show
@@ -13893,7 +15772,11 @@ behind the "Show more"/"Show less" toggle — when left empty, no toggle renders
 (wrapper around the `full` slot, `hidden` while collapsed), `toggle` (the "Show more"/"Show less"
 button — only rendered when the `full` slot has content).
 
-**Themeable custom properties:** shared tokens only — `--lr-color-border`, `--lr-color-surface`,
+**Themeable custom properties:** `--lr-source-card-compact-padding` (default `var(--lr-space-xs)`) —
+`[part='base']`'s padding while `compact`; `--lr-source-card-compact-gap` (default
+`var(--lr-space-2xs)`) — the gap between `[part='base']`'s rows while `compact`. Both apply only in
+the `compact` state, so a dense citation list can be tuned without re-pointing shared spacing tokens
+elsewhere. Plus shared tokens — `--lr-color-border`, `--lr-color-surface`,
 `--lr-color-text` / `-text-quiet`, `--lr-color-brand`, `--lr-radius`, `--lr-space-xs`/`-s`,
 `--lr-focus-ring-*`.
 
@@ -14092,6 +15975,14 @@ per-item stage label), `item-progress`,
 `item-error` (only for `stage="failed"` with `error` set), `item-actions`, `retry-button`,
 `cancel-button`, `empty`.
 
+In virtualized mode (at or above `virtualizeThreshold`) the rows live in the internal
+`lr-virtual-list`'s shadow root, and `item`, `item-header`, `item-name`, `item-progress`,
+`item-meta`, `item-error`, `item-actions`, `retry-button` and `cancel-button` are forwarded out
+through `exportparts`, so `lr-ingestion-queue::part(item)` and the rest keep working from a consumer
+stylesheet. `item-stage`, `item-chunk-count`, `item-embedding-status` and `item-attempts` are not
+forwarded, so those four are only reachable through `::part()` while the queue is below the
+threshold.
+
 **Themeable custom properties:** `--lr-ingestion-queue-max-height` (default `none`) — non-virtualized
 mode only: caps how tall the list grows before it scrolls internally. No effect once virtualized —
 retheme the internal list via `lr-virtual-list { --lr-virtual-list-height: … }` instead.
@@ -14278,7 +16169,12 @@ somewhere to land after a confirmation resolves), `item-row`, `item-text`, `conf
 `provenance` is unset; `item-body` is `hidden` while collapsed), `item-actions`, `add-button`,
 `remove-button`, `forget-all-button`.
 
-**Themeable custom properties:** shared tokens only.
+**Themeable custom properties:** `--lr-memory-panel-confidence-success-color` (default
+`var(--lr-color-success)`), `--lr-memory-panel-confidence-warning-color` (default
+`var(--lr-color-warning)`), `--lr-memory-panel-confidence-danger-color` (default
+`var(--lr-color-danger)`) — text color of an item's `confidence` indicator, one per confidence
+tier (`high`/`medium`/`low` against `thresholds`, the same tiering `lr-chunk-inspector` uses for
+its score bar). Plus shared tokens otherwise.
 
 **Optional peer deps:** none.
 
@@ -14348,10 +16244,37 @@ neither `error` nor `loading` is set), `row` (a plain element in this shadow roo
 virtualization threshold; exported from the internal `lr-virtual-list`'s own `row` part while
 virtualized — `::part(row)` reaches it either way), `group-header` (exported from the virtual list's
 `group` part; grouped/virtualized mode only), `select` (per-row `lr-checkbox`, omitted when
-`selectable` is false), `row-body` (carries `data-selected`), `metadata` (a `<dl>`; omitted when the
-chunk has none or while `presentation="compact"`), `metadata-entry`, `load-more-row`, `load-more`.
-
-**Themeable custom properties:** shared tokens only.
+`selectable` is false), `row-body` (carries `data-selected`), `row-body-selected` (additional part
+on a selected `row-body`), `metadata` (a `<dl>`; omitted when the chunk has none or while
+`presentation="compact"`), `metadata-entry`, `metadata-term` (the `<dt>` carrying a metadata key),
+`metadata-value` (the `<dd>` carrying its value), `load-more-row`, `load-more`.
+
+The per-row `lr-chunk-inspector`'s own parts are forwarded onward under a `chunk-` prefix —
+`chunk`, `chunk-current`, `chunk-score`, `chunk-score-current`, `chunk-score-bar`,
+`chunk-score-fill`, `chunk-score-fill-success`, `chunk-score-fill-warning`,
+`chunk-score-fill-danger`, `chunk-open-button`,
+`chunk-title`, `chunk-text`, `chunk-text-clamped`, `chunk-toggle`. Those elements sit two shadow
+hops deep while virtualized, so this forwarding is the only way to reach them.
+
+Selection state is exposed as the additional `row-body-selected` part name rather than through the
+`data-selected` attribute, because Shadow Parts forbids an attribute selector after `::part()`:
+`::part(row-body)[data-selected]` is invalid CSS, and while virtualized `::part()` is the only way
+in. `data-selected` is unchanged. 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. The `<dt>`/`<dd>`
+carry their own part names for the same class of reason — `::part()` matches a single element and
+cannot be followed by a descendant combinator, so `::part(metadata-entry) dt` reaches nothing.
+
+**Themeable custom properties:** `--lr-retrieval-results-selected-border` (default
+`var(--lr-color-brand)`) — the inline-start border color marking a selected row body
+(`::part(row-body-selected)`). A
+border rather than a fill by design: the row's own text (the nested chunk inspector's quiet-toned
+score line in particular) is sized and colored for the page's default surface, and a tinted
+background can drop it below the required contrast ratio, while a border-only indicator carries no
+such risk — so recoloring this hook is contrast-safe. It 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(row-body)[data-selected]` is invalid CSS — Shadow Parts forbids an attribute selector after
+`::part()` — which previously left re-pointing the library-wide `--lr-color-brand` token as the only
+lever, repainting every other brand surface with it. Plus shared tokens otherwise.
 
 **Optional peer deps:** none.
 
@@ -14462,7 +16385,14 @@ no stage has evidence), `evidence-row` (omitted for a stage with no evidence), `
 `evidence-metadata` (a `<dl>`), `evidence-metadata-row` (one key/value pair), `evidence-metadata-key`
 (`<dt>`), `evidence-metadata-value` (`<dd>`).
 
-**Themeable custom properties:** shared tokens only.
+**Themeable custom properties:** `--lr-retrieval-trace-active-border` (default
+`var(--lr-color-brand)`) — the border color of the `[part='evidence-row']` whose stage matches
+`activeStageId`, leaving every other row on the resting border token. It 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(evidence-row)[data-active]` is invalid CSS — Shadow Parts forbids an
+attribute selector after `::part()` — so marking the active stage previously meant overriding the
+library-wide `--lr-color-brand` token and repainting every other brand surface with it. Unset, it
+falls back to that token, so rendering is unchanged. Plus shared tokens otherwise.
 
 **Optional peer deps:** none.