@aceshooting/lyra-ui 16.0.0 → 18.0.0

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

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [llms-full.txt](../../llms-full.txt)
 - **Deprecations** none
 - **Optional peers** `dompurify`, `katex`, `marked`, `shiki` — see `llms/peers.md`
-- **Themeable via** 2 parts, 2 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 13 parts, 2 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---
@@ -36,6 +36,32 @@ not a delta — this component does no accumulation or ordering of its own.
   `<lr-code-block>`/`<lr-markdown>` support. Unset leaves the composed element's own default
   untouched.
 
+The rest of `<lr-markdown>`'s configuration surface forwards verbatim too, each defaulting to
+exactly `<lr-markdown>`'s own default so leaving it unset renders identically to before these
+properties existed:
+
+- `tabSize: number = 4` (attribute `tab-size`) — forwarded to the composed `<lr-markdown>`'s own
+  `tabSize`.
+- `htmlMode: 'sanitize' | 'escape' | 'trusted' = 'sanitize'` (attribute `html-mode`) — forwarded to
+  the composed `<lr-markdown>`'s own `htmlMode`.
+- `gfm: boolean = true` — forwarded to the composed `<lr-markdown>`'s own `gfm`.
+- `linkTarget: string | null = '_blank'` (attribute `link-target`) — forwarded to the composed
+  `<lr-markdown>`'s own `linkTarget`; the composed element always applies its own
+  `rel="noopener noreferrer"` guard whenever a `target` is emitted, including a forwarded
+  non-default value, and never a bare `opener`.
+- `internalLinkPrefix: string = ''` (attribute `internal-link-prefix`) — forwarded to the composed
+  `<lr-markdown>`'s own `internalLinkPrefix`.
+- `headingOffset: number = 0` (attribute `heading-offset`) — forwarded to the composed
+  `<lr-markdown>`'s own `headingOffset`.
+- `highlightCode: boolean = true` (attribute `highlight-code`) — forwarded to the composed
+  `<lr-markdown>`'s own `highlightCode`.
+- `headingAnchors: boolean = false` (attribute `heading-anchors`) — forwarded to the composed
+  `<lr-markdown>`'s own `headingAnchors`.
+- `math: boolean = false` — forwarded to the composed `<lr-markdown>`'s own `math`; the transitive
+  `katex` peer is requested only once this is set.
+- `maxHeight: string = ''` (attribute `max-height`) — forwarded to the composed `<lr-markdown>`'s
+  own `maxHeight`.
+
 **Exported helper:** `looksLikeMarkdown(text: string): boolean` — runs a fixed, ordered list of
 lightweight regexes (ATX heading, fenced code block, `**bold**`, `_italic_`, inline code, bullet
 list item, numbered list item, `[text](url)` link, blockquote) against the whole string and returns
@@ -57,7 +83,12 @@ never see that update happen. See `<lr-thinking-panel>`'s own reference at `llms
 
 **Slots:** none — content renders from `content`, not a slot.
 
-**CSS parts:** `base`, `cursor` (only rendered while `streaming` is `true`)
+**CSS parts:** `base`, `cursor` (only rendered while `streaming` is `true`), plus every part
+`<lr-markdown>` documents forwarded verbatim (no aliasing — none collides with `base`/`cursor`)
+from the composed `<lr-markdown>` in Markdown mode via `exportparts`: `content`, `heading`,
+`paragraph`, `list`, `code-block`, `inline-code`, `link`, `table`, `blockquote`, `img`, `math`. A
+host-level `lr-streaming-text::part(link)`/`::part(img)` rule reaches the rendered `<a>`/`<img>`
+exactly as the same rule does applied directly to `<lr-markdown>`.
 
 **Themeable custom properties:** `--lr-inline-cursor-width` (default
 `var(--lr-size-0-125rem)`, the shared inline cursor width), `--lr-inline-cursor-height` (default
@@ -72,8 +103,9 @@ does not register it separately), so its optional-peer module graph includes `ma
 stay on the peer-free plain-text path; Markdown rendering lazy-loads `marked` plus the default
 `dompurify` sanitizer and falls back to readable plain text if either is unavailable. Fenced code
 can additionally use `shiki`, whose absence only leaves code unhighlighted. The composed Markdown
-implementation contains the opt-in `katex` loader, but this wrapper does not enable its `math`
-property and therefore never requests `katex` itself.
+implementation contains the opt-in `katex` loader; this wrapper forwards its own `math` property
+(default `false`) to the composed element verbatim, so `katex` is requested only once a consumer
+sets `math` here.
 
 ```html
 <lr-streaming-text id="out" coalesce-ms="80" streaming></lr-streaming-text>
@@ -98,8 +130,11 @@ never be left stranded mid-window, and a stream restarting on a reused element c
 showing the previous stream's stale final content for the length of the window.
 
 Rendering itself is never reimplemented here: Markdown mode composes `<lr-markdown>` directly,
-forwarding this component's own `streaming` through as that component's `streaming` hint prop and
-`languages` verbatim; plain-text mode renders into a `white-space: pre-wrap` span instead. The
+forwarding this component's own `streaming` through as that component's `streaming` hint prop,
+`languages` verbatim, and the rest of `<lr-markdown>`'s configuration surface verbatim too
+(`tabSize`, `htmlMode`, `gfm`, `linkTarget`, `internalLinkPrefix`, `headingOffset`,
+`highlightCode`, `headingAnchors`, `math`, `maxHeight` — see **Properties** above); plain-text mode
+renders into a `white-space: pre-wrap` span instead. The
 blinking cursor degrades
 to a static, always-visible bar under `prefers-reduced-motion: reduce`. In plain-text mode it sits
 inline at the tail of the final character; in Markdown mode it renders as its own trailing block

package/llms/components/lr-suggestion-chips.md

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [llms-full.txt](../../llms-full.txt)
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 6 parts, 3 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 6 parts, 4 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---
@@ -25,12 +25,15 @@ identifier disappears, focus repairs to the nearest surviving occurrence without
 external focus move.
 
 **Properties:** `suggestions: readonly LyraChatSuggestion[] = []` (attribute: false) —
-`LyraChatSuggestion { suggestionId: string; label: string; icon?: string; detail?: string }`
+`LyraChatSuggestion { suggestionId: string; label: string; icon?: string; detail?: string; disabled?: boolean }`
 (exported here). Identifiers must be nonempty and unique; invalid/later duplicates are omitted with
 the first valid occurrence winning. The input is clone-owned, bounded, and frozen; reassign a new
 array after changing the sequence or a row. `icon` is an optional
 peer-neutral literal hint (for example, an emoji), rendered decoratively before the text, and
-`detail` is an optional secondary line. Empty renders nothing at all. `wrap: boolean = false`
+`detail` is an optional secondary line. `disabled` marks a suggestion non-actionable: its chip
+renders a genuinely disabled `<button>` (no roving tab stop, no hover/press affordance), activating
+it emits nothing, and arrow-key/Home/End roving navigation steps past it. Empty renders nothing at
+all. `wrap: boolean = false`
 (reflected) — wraps into multiple rows instead of a single horizontally scrollable line. `label?:
 string` — accessible name for the group. Omitting it uses the localized `suggestionsLabel`; an
 explicit empty string intentionally leaves the group unnamed.
@@ -49,7 +52,8 @@ cannot do (once the chips wrap, the row fills the available inline size and each
 start). `--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. All three are declared as `var()` fallbacks at the point of use, not
-on `:host`. Plus shared tokens `--lr-space-xs/-m/-2xs`,
+on `:host`. `--lr-suggestion-chips-disabled-opacity` (default `0.5`) — opacity of a chip whose
+suggestion sets `disabled`. 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`.
 

package/llms/components/lr-table.md

@@ -61,9 +61,11 @@ unchanged.
 headerCell?, width?, minWidth?, maxWidth?,
 resizable?, sortable?, sortValue?, defaultSortDir?: 'asc'|'desc', align?: 'start'|'end',
 priority?: 'medium'|'low',
-sticky?: 'start'|'end', editTrigger?: 'double-click'|'always', editValue?, editType?: 'text'|'number'|'select',
+sticky?: 'start'|'end', editTrigger?: 'double-click'|'always', editValue?, editLabel?: (row) => string,
+editType?: 'text'|'number'|'select',
 editOptions?: { value: string; label: string }[], footer?, cellStyle?, heatValue?,
-cell: (row) => unknown }` —
+cell: (row) => unknown }` — `cell` is required for every `editTrigger` except `'always'`, whose
+  persistent editor renders unconditionally so the table's render path never falls back to it —
   `sortValue(row) => string | number | null | undefined` supplies the comparable value backing
   client-mode sorting for that column: a finite number sorts numerically, a string sorts through an
   `Intl.Collator` built from the component's effective locale with `numeric: true` (so `item2`
@@ -103,13 +105,15 @@ cell: (row) => unknown }` —
   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);
-  `editTrigger: 'double-click'` opens a native editor on that cell's double-click (one cell at a
-  time), while `'always'` renders a persistent editor in every body cell from first paint, for a
+  `editTrigger: 'double-click'` opens a native editor on that cell's double-click, `F2`, or `Enter`
+  (one cell at a time), while `'always'` renders a persistent editor in every body cell 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'`, `'number'`, or `'select'` (a native `<select>` populated
   from `editOptions: { value: string; label: string }[]`, one `<option>` per entry in order; a
   `'select'` column with no `editOptions` renders an empty, valueless `<select>` instead of
-  throwing)
+  throwing); `editLabel(row) => string`, read once per row exactly like `editValue`/`cellTitle`,
+  overrides that editor's accessible name — omit it and every editor in the column shares the same
+  interpolated `tableEditCell` name instead (see the accessibility note under `editTrigger` below)
   `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;
@@ -131,8 +135,21 @@ cell: (row) => unknown }` —
   Enter commits and closes, Escape cancels and closes, and 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
+  - **Keyboard entry (`'double-click'` columns).** The resting (not-currently-editing) cell of a
+    `'double-click'` column is its own roving-focus stop — `tabindex="-1"`, carrying `[data-editable]`
+    — reachable once the row itself has focus: ArrowRight (ArrowLeft under RTL) enters at the first
+    editable cell in the row and steps forward through any further ones; ArrowLeft (ArrowRight under
+    RTL) steps back and, from the first editable cell, returns focus to the row. None of this is a Tab
+    stop — a table with a `'double-click'` column gains no new entry in the page's Tab order, only a
+    new arrow-reachable one — and a table with no `editTrigger` column at all renders no `tabindex`/
+    `[data-editable]` anywhere. `F2` or `Enter` on the focused cell opens its editor; `Enter` on the
+    row itself (no cell focused) still only activates the row. `editCell(rowKey, columnKey)` (see
+    Methods above) is the same open action as a public method. Closing the editor, by commit or by
+    cancel, returns focus to the cell that opened it.
+  - **Focus model (`'always'` columns).** 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/cell 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 `'text'`/`'number'` editor binds its `value` as a **content
@@ -151,8 +168,14 @@ cell: (row) => unknown }` —
     `<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.
+  - **Accessible name.** Each editor's name is `columns[].editLabel(row)` when the column defines
+    it, or otherwise the interpolated `tableEditCell` string (`Edit {column}`) — identical for every
+    row in that column, since the default has no row context. That default is adequate for
+    `'double-click'`, where at most one editor is ever open, but not for `'always'`: every row's
+    editor there is a permanent, individually focusable Tab stop, so leaving `editLabel` unset on an
+    `'always'` column exposes as many identically named controls as there are rows (e.g. fifty "Edit
+    Status" comboboxes), failing WCAG 2.4.6 and 1.3.1. Define `editLabel` for any `'always'` column
+    to give each row's editor its own name.
 - `hasHiddenPriorityColumns: boolean = false` (attribute `has-hidden-priority-columns`, reflected) —
   computed/read-only and true only while a priority column is actually hidden. It becomes false
   when `priorityColumnsVisible` reveals the columns. Measured via a `ResizeObserver` on
@@ -290,6 +313,14 @@ cell: (row) => unknown }` —
   rendered panel anyway, `expandedContentElement(rowKey)` (below) resolves that `<td>`;
   `rowElement(rowKey)` does not, because the panel is a sibling `<tr>` rather than part of the row
 - `canExpand?: (row: T) => boolean` (attribute: false) — optional per-row gate for expansion
+- `rowExpandLabel?: (row: T, expanded: boolean) => string | undefined` (attribute: false) —
+  accessible name for one row's expand/collapse chevron, read once per render for that row,
+  exactly like a column's `editLabel`/`cellTitle`; consumer-owned text used verbatim, never
+  passed through localization. Omit it and every chevron shares the same localized
+  `expand`/`collapse` name, which carries no row context — fine for a handful of rows, but each
+  chevron is its own Tab stop, so a long table otherwise announces the same two names over and
+  over with no way to tell the rows apart. There is no default row context to derive one from
+  here: this component has no row-header notion (`rowKey` is an opaque identity, not a label)
 - `expansionMode: 'none'|'single'|'multiple' = 'none'` (attribute `expansion-mode`, reflected) —
   mirrors `selectionMode` member for member, for expansion. The default `'none'` keeps
   `expandedRowKeys` fully consumer-controlled: an activation only reports `lr-row-expand-toggle`.
@@ -396,8 +427,14 @@ cell: (row) => unknown }` —
 - `expandedContentElement(rowKey)` — the rendered `[part='expanded-cell']` holding that row's
   `expandedContent(row)` output, or `null` when the row is not currently rendered, is not expanded,
   or the table sets no `expandedContent`
+- `editCell(rowKey, columnKey)` — opens the inline editor at that row/column pair, exactly as a
+  double-click, `F2`, or `Enter` on the cell's own focus stop would (see `columns[].editTrigger`
+  below) — the entry point for a consumer's own key binding or menu action. A no-op for an unknown
+  row key, an unknown column key, or a column with no `editTrigger`. For an `editTrigger: 'always'`
+  column (already open from first paint) it moves focus into that editor instead of opening
+  anything.
 
-All three exist for code that has to reach content a `cell(row)`/`expandedContent(row)` callback
+The first three exist for code that has to reach content a `cell(row)`/`expandedContent(row)` callback
 rendered into this component's shadow root — measuring it, scrolling it into view, or applying a
 style `::part()` cannot express, since only pseudo-classes may follow a part selector. One method per
 callback, and the split is not cosmetic: the expansion panel is a **sibling** `<tr part='expanded-row'>`

package/llms/components/lr-textarea.md

@@ -82,7 +82,7 @@ disabled state.
 | `enterKeyHint`           | `enterkeyhint`             | `string`                                                             | `''`         | Virtual-keyboard Enter-key hint forwarded to the native `<textarea>`.                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | `minlength`              | `minlength`                | `number \| undefined`                                                | `undefined`  | Minimum text length; forwarded to the native `<textarea>` and reported as `validity.tooShort`.                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | `maxlength`              | `maxlength`                | `number \| undefined`                                                | `undefined`  | Maximum text length; forwarded to the native `<textarea>` (which also stops typing past it) and reported as `validity.tooLong`.                                                                                                                                                                                                                                                                                                                                                                                   |
-| `debounce`               | `debounce`                 | `number \| undefined`                                                | `undefined`  | How long (ms) to wait after the last keystroke before emitting one `lr-input-settled`, while `input`/`lr-input` keep firing per keystroke as before. Omitted, `0`, or non-finite means no debounce: `lr-input-settled` never fires. A pending debounce is flushed immediately by `change`/Enter/blur and cancelled with no stray settle by disconnection and a programmatic `value` write. Shares its `DebounceController` primitive with `lr-filter-bar`'s own per-filter `debounce` and with `lr-input`'s identical property. |
+| `debounce`               | `debounce`                 | `number \| undefined`                                                | `undefined`  | How long (ms) to wait after the last keystroke before emitting one `lr-input-settled`, while `input`/`lr-input` keep firing per keystroke as before. Omitted, `0`, or non-finite means no debounce: `lr-input-settled` never fires. A pending debounce is flushed immediately by `change`/Enter/blur and cancelled with no stray settle by disconnection and by a programmatic `value` write that changes the value. A write of the value already held leaves it pending, so a framework binding that writes the just-typed value back on each render (the controlled-input pattern) still settles. Shares its `DebounceController` primitive with `lr-filter-bar`'s own per-filter `debounce` and with `lr-input`'s identical property. |
 | `name`                   | `name`                     | `string`                                                             | `''`         | Form field name.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | `disabled`               | `disabled`                 | `boolean`                                                            | `false`      | Disables the control.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | `required`               | `required`                 | `boolean`                                                            | `false`      | Participates in native constraint validation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |

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

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [llms-full.txt](../../llms-full.txt)
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 23 parts, 34 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 23 parts, 35 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---
@@ -178,6 +178,12 @@ mode the raised tone is already distinct from the page, so this panel never had
 reads-as-a-hole problem the family exists to fix. Setting `--lr-overlay-surface` still repaints it
 along with every other popup.
 
+`--lr-positioning-strategy` (16.0.0) — the `popup` panel reads this same cascading
+`absolute`/`fixed` override documented on `<lr-popover>` when it is (re)positioned, falling back to
+its own `fixed` default when nothing is set. There is no per-instance `positioning-strategy`
+property on `<lr-time-input>`; set the custom property on `:root`, a theme, or one clipping
+ancestor to change every unset time input beneath it.
+
 ```html
 <lr-time-input
   label="Start time"

package/llms/components/lr-tool-call-chip.md

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [llms-full.txt](../../llms-full.txt)
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 10 parts, 9 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 10 parts, 10 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---
@@ -86,6 +86,12 @@ The anchored detail tooltip is a floating surface and paints from the **shared o
 declared on `:host`, so one declaration on `:root` — or on any ancestor, to scope it — retints this
 surface together with every other floating surface in the library. `--lr-overlay-radius` (default `var(--lr-radius)`) is the matching corner radius.
 
+`--lr-positioning-strategy` (16.0.0) — the detail tooltip reads this same cascading
+`absolute`/`fixed` override documented on `<lr-popover>` when it is (re)positioned, falling back to
+its own `fixed` default when nothing is set. There is no per-instance `positioning-strategy`
+property on `<lr-tool-call-chip>`; set the custom property on `:root`, a theme, or one clipping
+ancestor to change every unset chip beneath it.
+
 **Optional peer deps:** none.
 
 ```html

package/llms/components/lr-tour.md

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [llms-full.txt](../../llms-full.txt)
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 12 parts, 6 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 12 parts, 7 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---
@@ -104,6 +104,12 @@ shared ceiling that keeps any floating surface inside a narrow viewport. `lr-tou
 retuning `--lr-theme-popover-viewport-clamp` once at `:root` narrows or widens all three together
 rather than per component.
 
+`--lr-positioning-strategy` (16.0.0) — the step popover reads this same cascading `absolute`/`fixed`
+override documented on `<lr-popover>` when a step is (re)positioned, falling back to its own `fixed`
+default when nothing is set. There is no per-instance `positioning-strategy` property on `<lr-tour>`;
+set the custom property on `:root`, a theme, or one clipping ancestor to change every unset tour
+beneath it.
+
 **Known gotchas:**
 
 - By default the spotlighted target is **non-interactive**: it stays visible and announceable (not

package/llms/components/lr-usage-badge.md

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [llms-full.txt](../../llms-full.txt)
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 7 parts, 4 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 7 parts, 5 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---
@@ -56,6 +56,12 @@ family** (16.0.0): `--lr-overlay-surface` (default `var(--lr-color-surface-overl
 ancestor, to scope it — retints this surface together with every other floating surface in the
 library. `--lr-overlay-radius` (default `var(--lr-radius)`) is the matching corner radius.
 
+`--lr-positioning-strategy` (16.0.0) — the breakdown tooltip reads this same cascading
+`absolute`/`fixed` override documented on `<lr-popover>` when it is (re)positioned, falling back to
+its own `fixed` default when nothing is set. There is no per-instance `positioning-strategy`
+property on `<lr-usage-badge>`; set the custom property on `:root`, a theme, or one clipping
+ancestor to change every unset usage badge beneath it.
+
 ```html
 <lr-chat-message message-role="assistant" status="sent">
   <lr-usage-badge

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

@@ -101,6 +101,17 @@ list's `base` scroll container exposes horizontal scrolling for that explicit op
   number `56` and fixes every row to that many pixels. Property callers assign a number, not a
   numeric string. Anything else (non-numeric, zero, negative, non-finite) safely canonicalizes to
   `'auto'` rather than throwing.
+- `rowProjection: 'shadow' | 'light' = 'shadow'` (attribute `row-projection`) — where
+  `renderItem`'s output is instantiated. `'shadow'` (default) stamps it inside this component's own
+  shadow root, so only inherited custom properties and the public row parts reach it. `'light'`
+  renders the windowed rows into the host's own light DOM instead, assigned into the shadow viewport
+  through internal named slots, so ordinary document CSS styles a virtualized row exactly as it
+  styles the same row unvirtualized. The component keeps owning windowing, measurement, spacer
+  sizing, `scrollToIndex()`, the external-scroller mode and the ARIA contract either way, and
+  positioning stays on the shadow-side `[part="row"]` wrapper that document CSS cannot select — so
+  consumer styles can never break windowing. Any other value canonicalizes to `'shadow'`. Left
+  unset, the rendered output is byte-identical to before and the host's light DOM stays empty.
+  See **Light-DOM row projection** below for the trade-offs it carries.
 - `itemRole: 'listitem' | 'row' = 'listitem'` (attribute `item-role`) — `'listitem'` (default)
   preserves the plain `role="list"`/`role="listitem"` mapping with `aria-setsize`/`aria-posinset`.
   `'row'` additionally maps `[part="base"]` to `role="rowgroup"`, `[part="spacer"]` to
@@ -355,4 +366,46 @@ default estimate with sparse `ResizeObserver` measurements for rows that have ac
   decides: groups render before the rows, so an active row wins while (and only while) it needs to,
   which is right — a group header is a non-interactive `pointer-events: none` label.
 
+### Light-DOM row projection
+
+`rowProjection="light"` exists for one shape: an application whose list rows are already styled by
+its own global stylesheet, and which therefore could not adopt virtualization without rehoming a
+dozen descendant rules per row into a new custom element or a growing set of custom properties. In
+projection mode the windowed rows render into the host's own light DOM, so ordinary document CSS
+reaches row content directly.
+
+Positioning, measurement and semantics stay where they were. The `[part="row"]` wrapper remains in
+the shadow root and keeps `position: absolute`, the per-frame `transform`, `role`, `aria-setsize`/
+`aria-posinset` (or `aria-rowindex`) and the `ResizeObserver` box — document CSS cannot select it,
+so consumer styles can never break windowing. The whole part vocabulary (`base`, `spacer`, `row`,
+`group`, `sticky-group`) keeps matching in both modes, and `row-height="auto"` still measures
+projected content because the light row is an ordinary in-flow child of that wrapper.
+
+`projectedRows: HTMLElement[]` returns the projected light-DOM row wrappers in item order, and is
+empty outside projection mode. The exported type is `LyraVirtualListRowProjection`; the reserved
+attributes marking library-owned light-DOM nodes are exported as `VIRTUAL_LIST_ROW_ATTRIBUTE`
+(`data-lr-virtual-list-row`) and `VIRTUAL_LIST_STICKY_ATTRIBUTE` (`data-lr-virtual-list-sticky`).
+
+**Known gotchas, all inherent to handing the cascade back to the consumer:**
+
+- **One component-owned wrapper sits between the host and your markup.** A slot cannot assign a text
+  node or a multi-root fragment by attribute, so each row's content lives inside a wrapper carrying
+  `data-lr-virtual-list-row`. Descendant selectors (`lr-virtual-list .row-title`) port unchanged;
+  child combinators (`lr-virtual-list > .row`), `:nth-child`, `:first-child` and sibling combinators
+  written against the unvirtualized markup do not. `:nth-child` on the wrappers reflects the current
+  *window*, not the item index.
+- **`closest('[part="row"]')` stops resolving.** A delegated listener on the host now sees an
+  un-retargeted `event.target` inside the light DOM. Use `closest('[data-lr-virtual-list-row]')`.
+- **The document cascade now reaches row content**, including resets and element-level rules that
+  previously could not, so a projected row can look different from the same row in shadow mode.
+- **Per-row light-DOM state does not survive a disconnect/reconnect.** Disconnect removes the
+  projected rows completely (no rows, no markers, no anchor left behind), so a reparenting move
+  rebuilds them. Scroll position, measurements and the window are unaffected — they live in
+  component state, not in the rows.
+- **Projection activates one task after hydration.** A server render has no DOM to project into, so
+  the first window is shadow-rendered, hydration matches the server markup, and the rows then swap
+  into the light DOM on the next task.
+- **A row taken out of flow collapses its wrapper.** `position: fixed`/`absolute` or
+  `display: none` on your own row leaves nothing for the wrapper to measure.
+
 ---

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

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [llms-full.txt](../../llms-full.txt)
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 17 parts, 27 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 17 parts, 28 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---
@@ -43,8 +43,11 @@ popup. Ordinary keyboard behavior resumes after composition.
 **Exported types:** `LyraVoiceCatalogEntry extends LyraCatalogEntry { language?: string;
 description?: string; previewUrl?: string }` — `language`/`description` render as a quiet
 `[part="option-meta"]` second line. Voice catalogs use the shared
-`LyraCatalog<LyraVoiceCatalogEntry>` homogeneous readonly union documented under `lr-model-select`.
-The public `size` property uses `LyraSize`, including the long-form aliases.
+`LyraCatalog<LyraVoiceCatalogEntry>` homogeneous readonly union documented under `lr-model-select`,
+including the shared `disabled` field: a disabled voice row cannot be selected by click or keyboard
+and is stepped over by arrow-key/Home/End navigation, but its own `[part="option-preview"]` stays
+independently clickable, since previewing a voice is a separate affordance from selecting it. The
+public `size` property uses `LyraSize`, including the long-form aliases.
 `LyraVoicePickerSelectionDirection = 'forward' | 'backward' | 'none'` is the native
 selection direction exposed in free-text mode.
 
@@ -204,6 +207,7 @@ trigger), `expand-icon`, `empty`, `hint`, `error`.
 - `--lr-voice-picker-option-selected-font-weight` — Selected option label weight. Default: `var(--lr-font-weight-semibold)`.
 - `--lr-voice-picker-option-synthetic-border-style` — Synthetic stale-value row border style. Default: `dashed`.
 - `--lr-voice-picker-option-synthetic-border-color` — Synthetic stale-value row border color. Default: `var(--lr-color-border)`.
+- `--lr-voice-picker-option-disabled-opacity` — Opacity of an option row whose catalog entry sets `disabled`. Default: `0.5`.
 - `--lr-voice-picker-option-synthetic-font-style` — Synthetic stale-value option-label font style. Default: `italic`.
 - `--lr-voice-picker-preview-hover-bg` — Preview hover fill. Default: `var(--lr-color-brand-quiet)`.
 - `--lr-voice-picker-preview-hover-color` — Preview hover icon. Default: `var(--lr-color-brand)`.