@aceshooting/lyra-ui 5.1.0 → 5.2.0

package/llms/components/lr-tour.md

@@ -76,7 +76,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

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

@@ -33,3 +33,26 @@ as a root rather than being dropped. `activeSpanId: string | null = null`
 `showTokens`/`showCost`), `row` (`role="treeitem"`), `toggle`, `icon`, `name`, `detail`, `status-text`,
 `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.

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

@@ -34,18 +34,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).
 
@@ -129,5 +145,7 @@ 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.
 
 ---

package/llms/components/lr-tree.md

@@ -34,18 +34,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).
 
@@ -129,5 +145,7 @@ 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.
 
 ---

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

@@ -29,10 +29,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.
@@ -59,7 +88,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.
@@ -69,12 +99,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`.
 
@@ -82,8 +135,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),
@@ -112,6 +168,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
@@ -139,7 +209,26 @@ 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.
 
 ---

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

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

package/llms/components/lr-widget.md

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

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

@@ -46,7 +46,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

package/llms/peers.md

@@ -14,7 +14,7 @@ If the peer is genuinely absent, the component falls back to an empty/degraded r
 
 | Peer | Range | Needed by |
 |---|---|---|
-| `@aceshooting/lyra-flags` | `workspace:^2.0.0` | `lr-flag` |
+| `@aceshooting/lyra-flags` | `workspace:^2.0.0` | `lr-flag`, `lr-phone-input` |
 | `@aiden0z/pptx-renderer` | `^1.2.4` | `lr-pptx-viewer` |
 | `@sgratzl/chartjs-chart-boxplot` | `^4.4.0` | `lr-box-plot` |
 | `chart.js` | `^4.5.0` | `lr-bar-chart`, `lr-box-plot`, `lr-bubble-chart`, `lr-chart`, `lr-doughnut-chart`, `lr-histogram`, `lr-line-chart`, `lr-pie-chart`, `lr-polar-area-chart`, `lr-radar-chart`, `lr-scatter-chart` |

package/llms/shared.md

@@ -21,7 +21,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
@@ -104,17 +104,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 */
@@ -286,7 +347,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.
@@ -319,3 +380,64 @@ Not custom elements — infrastructure the components compose. Importable via
 `custom-elements.json`, the editor metadata, and every file under `llms/` are regenerated by
 `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.

package/llms/tokens.md

@@ -16,7 +16,7 @@ For a ready-made light/dark base, import `@aceshooting/lyra-ui/theme.css` once a
 Per-component `--lr-<component>-*` custom properties (listed in each component's own section)
 override a single element without touching the shared layer.
 
-## Themeable inputs (228)
+## Themeable inputs (233)
 
 | Internal token | `--lr-theme-*` input | Fallback |
 |---|---|---|
@@ -41,7 +41,7 @@ override a single element without touching the shared layer.
 | `--lr-color-on-danger` | `--lr-theme-color-danger-on-loud` | `#fff` |
 | `--lr-color-on-neutral` | `--lr-theme-color-neutral-on-loud` | `#fff` |
 | `--lr-color-overlay` | `--lr-theme-color-overlay` | `rgb(0 0 0 / 0.5)` |
-| `--lr-color-overlay-strong` | `--lr-theme-color-overlay` | `rgb(0 0 0 / 0.92)` |
+| `--lr-color-overlay-strong` | `--lr-theme-color-overlay-strong` | `var(--lr-theme-color-overlay, rgb(0 0 0 / 0.92))` |
 | `--lr-color-no-data` | `--lr-theme-color-no-data` | `rgb(128 128 128 / 25%)` |
 | `--lr-font-mono` | `--lr-theme-font-family-mono` | `ui-monospace, SFMono-Regular, Menlo, Consolas, monospace` |
 | `--lr-space-xs` | `--lr-theme-space-xs` | `0.25rem` |
@@ -211,7 +211,12 @@ override a single element without touching the shared layer.
 | `--lr-transition-base` | `--lr-theme-transition-normal` | `180ms ease-out` |
 | `--lr-transition-ambient` | `--lr-theme-transition-slow` | `1.8s ease-in-out` |
 | `--lr-opacity-disabled` | `--lr-theme-opacity-disabled` | `0.5` |
+| `--lr-hover-brightness` | `--lr-theme-hover-brightness` | `1.08` |
+| `--lr-popover-viewport-clamp` | `--lr-theme-popover-viewport-clamp` | `92vw` |
+| `--lr-focus-ring-width` | `--lr-theme-focus-ring-width` | `2px` |
 | `--lr-focus-ring-color` | `--lr-theme-color-focus` | `var(--lr-color-brand)` |
+| `--lr-focus-ring-offset` | `--lr-theme-focus-ring-offset` | `2px` |
+| `--lr-icon-button-size` | `--lr-theme-icon-button-size` | `2.5rem` |
 | `--lr-color-surface` | `--lr-theme-color-surface-default` | `#1a1a1a` |
 | `--lr-color-surface-raised` | `--lr-theme-color-surface-raised` | `#22272e` |
 | `--lr-color-text` | `--lr-theme-color-text-normal` | `#f2f2f2` |
@@ -249,7 +254,7 @@ override a single element without touching the shared layer.
 | `--lr-graph-cat-7` | `--lr-theme-graph-cat-7` | `#79e2ef` |
 | `--lr-graph-cat-8` | `--lr-theme-graph-cat-8` | `#e4e7eb` |
 
-## Derived tokens (276)
+## Derived tokens (278)
 
 Computed from the layer above; not directly themeable.
 
@@ -276,7 +281,7 @@ Computed from the layer above; not directly themeable.
 | `--lr-color-on-danger` | `var(--lr-theme-color-danger-on-loud, #fff)` |
 | `--lr-color-on-neutral` | `var(--lr-theme-color-neutral-on-loud, #fff)` |
 | `--lr-color-overlay` | `var(--lr-theme-color-overlay, rgb(0 0 0 / 0.5))` |
-| `--lr-color-overlay-strong` | `var(--lr-theme-color-overlay, rgb(0 0 0 / 0.92))` |
+| `--lr-color-overlay-strong` | `var(--lr-theme-color-overlay-strong, var(--lr-theme-color-overlay, rgb(0 0 0 / 0.92)))` |
 | `--lr-color-no-data` | `var(--lr-theme-color-no-data, rgb(128 128 128 / 25%))` |
 | `--lr-font-mono` | `var(--lr-theme-font-family-mono, ui-monospace, SFMono-Regular, Menlo, Consolas, monospace)` |
 | `--lr-space-xs` | `var(--lr-theme-space-xs, 0.25rem)` |
@@ -450,10 +455,12 @@ Computed from the layer above; not directly themeable.
 | `--lr-transition-base` | `var(--lr-theme-transition-normal, 180ms ease-out)` |
 | `--lr-transition-ambient` | `var(--lr-theme-transition-slow, 1.8s ease-in-out)` |
 | `--lr-opacity-disabled` | `var(--lr-theme-opacity-disabled, 0.5)` |
-| `--lr-focus-ring-width` | `2px` |
+| `--lr-hover-brightness` | `var(--lr-theme-hover-brightness, 1.08)` |
+| `--lr-popover-viewport-clamp` | `var(--lr-theme-popover-viewport-clamp, 92vw)` |
+| `--lr-focus-ring-width` | `var(--lr-theme-focus-ring-width, 2px)` |
 | `--lr-focus-ring-color` | `var(--lr-theme-color-focus, var(--lr-color-brand))` |
-| `--lr-focus-ring-offset` | `2px` |
-| `--lr-icon-button-size` | `2.5rem` |
+| `--lr-focus-ring-offset` | `var(--lr-theme-focus-ring-offset, 2px)` |
+| `--lr-icon-button-size` | `var(--lr-theme-icon-button-size, 2.5rem)` |
 | `--lr-safe-area-inline-start` | `env(safe-area-inset-right, 0px)` |
 | `--lr-safe-area-inline-end` | `env(safe-area-inset-left, 0px)` |
 | `--lr-color-surface` | `var(--lr-theme-color-surface-default, #1a1a1a)` |