@aceshooting/lyra-ui 5.1.0 → 6.0.0

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

@@ -43,18 +43,34 @@ 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
 actions) after the built-in `rowActions` output in each row's `actions` slot; events it fires reach
 the host normally and never trigger `lr-select`. Unset renders only the built-in `rowActions`.
 `renderLeading?: (thread: ChatThread) => TemplateResult` (attribute: false) — renders non-interactive
-leading content in each virtualized row. `renderMeta?: (thread: ChatThread) => TemplateResult`
-(attribute: false) — appends structured metadata in the row's meta region.
+leading content in each virtualized row. `renderExcerpt?: (thread: ChatThread) => TemplateResult`
+(attribute: false) — renders rich content into the row item's own `excerpt` slot, winning over the
+plain-string `excerpt` property (e.g. a server-highlighted search-match snippet), while leaving the
+built-in title layout and inline-rename affordance untouched. `renderMeta?: (thread: ChatThread) =>
+TemplateResult` (attribute: false) — appends structured metadata in the row's meta region.
 `renderRowContent?: (thread: ChatThread) => TemplateResult` (attribute: false) — replaces the
 conversation item's title/excerpt/meta content area with custom non-interactive row content.
 `formatGroupLabel?: (key: ThreadBucketKey, date?: Date) => string` (attribute: false) — overrides
@@ -72,20 +88,69 @@ 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-excerpt`/`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).
+reach callback-rendered descendants through these parts). `row-excerpt` wraps `renderExcerpt`
+output, which is slotted into the row item's own `excerpt` slot.
+
+Data mode additionally forwards each row `<lr-conversation-item>`'s own parts under a `row-item-`
+prefix: `row-item-base`, `row-item-option`, `row-item-leading`, `row-item-content`,
+`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`, `renderExcerpt`,
+`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']}

package/llms/components/lr-time-input.md

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

package/llms/components/lr-time-range.md

@@ -24,6 +24,10 @@ consumer-facing `disabled` property/attribute itself.
 - `start: number = 0`
 - `end: number = 100`
 - `step: number = 1`
+- `size: '2xs' | 'xs' | 's' | 'm' | 'l' | 'xl' = 'm'` (reflected) — visual size; proportionally
+  scales the handle, track, and preset buttons via a single `--lr-time-range-size-scale` multiplier
+  (not pixel-matched to `lr-input`'s row-height scale — this component's own dimensions aren't on
+  that ladder); the drag hit-area never shrinks below 24px (WCAG 2.5.8)
 - `disabled: boolean = false` (reflected)
 - `startLabel: string = 'Range start'` (attribute `start-label`) — `aria-label` for the start handle
 - `endLabel: string = 'Range end'` (attribute `end-label`) — `aria-label` for the end handle
@@ -41,11 +45,31 @@ 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.
+
+One additional component-local property, `--lr-time-range-size-scale` (unitless multiplier,
+default 1, automatically set based on the `size` property), scales the handle, track, and preset
+button dimensions proportionally — unset, it defaults to 1 (size='m', no scaling).
+
+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.
 

package/llms/components/lr-token-input.md

@@ -17,15 +17,50 @@ 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), `size: '2xs' | 'xs' | 's' | 'm' | 'l' | 'xl' = 'm'` (reflected — same scale as `lr-input`'s
+`size`, scaling the input-wrapper's row height and text size across six tiers; the remove button's
+hit area stays fixed at `40px` across all sizes), `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.
 
-**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).
+**`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-padding` (the input-wrapper padding, scaled by
+`size`), `--lr-token-input-font-size` (the input-wrapper and token font size, scaled by `size`),
+`--lr-token-input-control-min-height` (the input-wrapper's block-size floor, scaled by `size`),
+`--lr-token-input-control-height` (exact input-wrapper height — undeclared by default, leaving the
+`--lr-token-input-control-min-height` floor only; set it to a length to both floor and cap the row,
+e.g. to pixel-match a sibling field in the same toolbar row), `--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`), `--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`).

package/llms/components/lr-tool-approval-dialog.md

@@ -31,6 +31,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
@@ -43,21 +47,26 @@ 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.
+  `pending: 'approve' | 'deny' | null = null` (reflected) — which decision is awaiting host
+  resolution while an `lr-approve`/`lr-deny` listener has called `preventDefault()` on the
+  now-cancelable event; the pending button shows `loading`, the other is `disabled` (Approve is
+  also still `disabled` while an in-progress edit is invalid JSON, independent of `pending`).
+  Escape/backdrop dismissal is suppressed while `pending` is set. Finalize by calling
+  `close('approve'|'deny')`, or clear `.pending` back to `null` to bounce back to the undecided
+  state; `pending` also resets to `null` every time the dialog re-opens.
 
 **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
 already closed.
 
 **Events:** `lr-approve` (`detail: { args: unknown }` — the current, already-parsed arguments: the
-original `args` prop, or the user's edited-and-validated version if an edit was in progress; always
-followed by `lr-close` with reason `'approve'`), `lr-deny` (no detail — `this.emit('lr-deny')` is
-called with no second argument, so per the DOM spec's `CustomEventInit` default, `event.detail` is
-`null`, not `undefined`; always followed by `lr-close` with reason `'deny'`), `lr-close`
+original `args` prop, or the user's edited-and-validated version if an edit was in progress.
+Cancelable: a listener calling `preventDefault()` sets `pending` to `'approve'` instead of
+closing; otherwise always followed by `lr-close` with reason `'approve'`), `lr-deny` (no detail —
+`this.emit('lr-deny')` is called with no second argument, so per the DOM spec's `CustomEventInit`
+default, `event.detail` is `null`, not `undefined`. Cancelable, same `pending` mechanism, setting
+`pending` to `'deny'`; otherwise always followed by `lr-close` with reason `'deny'`), `lr-close`
 (`detail: ToolApprovalDialogCloseReason` — fired exactly once per dismissal, via Escape, a backdrop
 click, the Approve/Deny buttons, or a `close()` call)
 
@@ -65,7 +74,12 @@ click, the Approve/Deny buttons, or a `close()` call)
 rendered before the built-in Deny/Edit/Approve buttons.
 
 **CSS parts:** `backdrop`, `panel`, `header`, `tool-name`, `body`, `args-view`, `args-editor`, `error`,
-`footer`, `deny-button`, `edit-button`, `approve-button`
+`footer`, `deny-button`, `edit-button`, `approve-button`,
+`deny-button-base`, `deny-button-label`, `deny-button-start`, `deny-button-end`,
+`deny-button-spinner`, `approve-button-base`, `approve-button-label`, `approve-button-start`,
+`approve-button-end`, `approve-button-spinner` (`deny-button`/`approve-button` are each an
+`<lr-button>` host; these five per-button parts are re-exported from its own `lr-button` parts via
+`exportparts`; `edit-button` stays a plain `<button>`, unaffected by this).
 
 **Themeable custom properties:** `--lr-tool-approval-dialog-overlay-color` (default
 `rgb(0 0 0 / 0.5)` — the backdrop scrim color; component-specific since no shared overlay token
@@ -127,5 +141,15 @@ shared composed-tree focus traversal used by the other modal families.
   this a mobile browser (notably iOS Safari, which defaults textarea `autocapitalize` to
   `'sentences'`) could auto-capitalize or auto-correct key/value text as the user edits, silently
   corrupting the JSON.
+- `deny-button`/`approve-button` are `<lr-button>` hosts (`variant="neutral"`/`"brand"` — this
+  component has no `tone` property) — `--lr-button-*` theming reaches them directly. A consumer
+  previously styling `::part(deny-button)`/`::part(approve-button)` for
+  padding/border/font/`:hover`/`:focus-visible` must move that CSS onto the re-exported
+  `deny-button-base`/`approve-button-base` sub-parts instead. `edit-button` is unaffected and stays
+  a raw `<button>`.
+- An `lr-approve`/`lr-deny` listener can call `preventDefault()` to keep the decision open while
+  its own async work is in flight — see `pending` above. While `pending` is set, Escape/backdrop
+  dismissal is suppressed, so a consumer that never resolves the pending decision leaves the
+  dialog open until it clears `.pending` or calls `close()` directly itself.
 
 ---

package/llms/components/lr-tool-timeline.md

@@ -53,4 +53,9 @@ 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"`.

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.
 
 ---