@aceshooting/lyra-ui 1.1.0 → 2.0.0

package/llms-full.txt

@@ -23,6 +23,17 @@ here.
 - **Chart family** — `lyra-chart` (core), typed subclasses, `lyra-histogram`, `lyra-box-plot`,
   `lyra-lite-chart` (dependency-free bar/line alternative, no peer deps)
 - **Map & file-input** — `lyra-map`, `lyra-file-input`
+- **Conversation & Agent UI** — `lyra-dialog`/`confirm()`, `lyra-tabs`, `lyra-checkbox`,
+  `lyra-switch`, `lyra-json-viewer`, `lyra-live-region`, `lyra-markdown`, `lyra-chat-message`,
+  `lyra-typing-indicator`, `lyra-tool-call-chip`, `lyra-tool-result-view` (+ its renderer registry),
+  `lyra-tool-result-dialog`, `lyra-chat-composer`, `lyra-attachment-chip`, `lyra-stream-status`,
+  `lyra-virtual-list`, `lyra-conversation-item`, `lyra-model-select`, `lyra-slider`,
+  `lyra-tool-select-dialog`, `lyra-citation-badge`, `lyra-source-list`/`lyra-source-card`,
+  `lyra-app-rail`, `lyra-responsive-panel`, `lyra-mention-popover`, `lyra-streaming-text`,
+  `lyra-thinking-panel`, `lyra-generation-status`, `lyra-code-block`, `lyra-tool-approval-dialog`,
+  `lyra-tool-param-form`, `lyra-menu`/`lyra-menu-item`, `lyra-chip`/`lyra-chip-group`,
+  `lyra-model-settings-panel`, `lyra-context-meter`, `lyra-dock-panel`, `lyra-document-preview`,
+  `lyra-media-card`, `lyra-attachment-trigger`, `lyra-kbd`, `lyra-result-card`/`lyra-result-field`
 - **Cross-cutting notes** — packaging and adoption caveats that apply across the whole library
 
 ---
@@ -90,8 +101,13 @@ Not a custom element itself — infrastructure every `lyra-*` component in the l
   scroll lock (used by `lyra-widget`'s fullscreen mode); safe to acquire/release more than once
   concurrently, restores the original `overflow` only once the last outstanding lock releases.
 - **`rtl.ts` → `isRtl(el): boolean`** — reads `getComputedStyle(el).direction === 'rtl'`, for the
-  pointer/keyboard math (drag ratios, arrow-key direction) in `lyra-split` and `lyra-time-range`
-  that reasons about physical left/right and can't rely on logical CSS properties alone.
+  pointer/keyboard math (drag ratios, arrow-key direction) in `lyra-split`, `lyra-time-range`, and
+  `lyra-dock-panel` that reasons about physical left/right and can't rely on logical CSS properties
+  alone. The same module also exports `rtlAwareSide(side, el)` and `rtlAwarePlacement(placement,
+  el)`, which swap a physical `'left'`/`'right'` value (or the `left`/`right` component of a
+  Floating UI `Placement` string) under RTL and pass it through unchanged under LTR — for a caller
+  that means "anchor to my trailing edge" but has to hand `place()` a physical placement. `lyra-menu`
+  resolves its `placement` property through `rtlAwarePlacement()` before positioning.
 
 **Known gotchas:**
 - `formResetCallback()`'s restore-to-constructed-default behavior (both here and in
@@ -211,6 +227,9 @@ another unnamed combobox in the same form.
 - naming drift from Web Awesome parity: the shipped attribute is **`with-clear`**, not
   `clearable` (which is what `<wa-combobox>` uses) — don't copy-paste WA docs assuming a 1:1
   attribute name here.
+- a host-level `aria-label` attribute on `<lyra-combobox>` now takes priority over `label`/
+  `placeholder`/`"Combobox"` when resolving the accessible name on `[part="combobox-input"]` —
+  previously it was silently ignored. Matches the same fallback on `<lyra-select>`.
 - no `size` variant (small/medium/large) unlike sibling `lyra-toast-item`.
 - `aria-required` reflects `required` immediately; `aria-invalid`, by contrast, only reflects
   **after the field has been touched** (first `blur`) — a `required` field with a validity error
@@ -242,6 +261,16 @@ combobox does, and the popup reuses `internal/positioner.ts` for placement.
 Single-select only, with no `filter`/`source`/`with-clear`/`max-options-visible`/`empty-text`/
 `max-render`/`multiple` surface — reach for `<lyra-combobox>` instead whenever any of those apply.
 
+**Single-option auto-commit.** When exactly one option is enabled (regardless of how many disabled
+ones exist alongside it), the popup never opens at all: a click, Enter, Space, ArrowDown, or ArrowUp
+on the trigger commits that sole option directly, and the trigger renders as a plain `role="button"`
+with no chevron/`aria-haspopup`/`aria-expanded`/`aria-controls`/`aria-activedescendant` rather than a
+combobox with a permanently inert popup state. This is unconditional default behavior, not
+opt-in — opening a one-row list to pick the only available choice is pure friction with no real
+decision behind it. It never changes `value`/validity defaults on its own: an unselected
+single-option select stays unselected (and a `required` one stays invalid) exactly like the
+multi-option case, until the trigger is actually activated.
+
 **Properties:**
 - `placeholder: string = ''`
 - `disabled: boolean = false` (reflected)
@@ -252,6 +281,8 @@ Single-select only, with no `filter`/`source`/`with-clear`/`max-options-visible`
 - `errorText: string = ''` (attribute `error-text` — static error copy shown below the hint;
   overridden by slotted `error` content when provided)
 - `open: boolean = false` (reflected)
+- `size: 'xs'|'s'|'m'|'l'|'xl' = 'm'` (reflected — same scale as `lyra-toast-item`'s `size`, for
+  compact toolbar placements that don't fit the default trigger height)
 - `value: string` — a getter/setter; always a single string (no `multiple` mode)
 
 **Events:** `change` (native-style — selection changed), `input` (fired alongside `change` on every
@@ -293,6 +324,13 @@ secondary line, when `sub` is set), `expand-icon`, `error`, `hint`
 - `aria-required` on the trigger reflects `required` immediately; `aria-invalid` only reflects once
   the trigger has been blurred (touched) at least once, mirroring `lyra-combobox`'s own input.
   Blurring the trigger (Tab away) closes an open listbox, the same as a native `<select>`'s popup.
+- The trigger's accessible name now checks a host-level `aria-label` attribute first, before falling
+  back to `label`/`placeholder`/`"Select"` — a plain `aria-label` on `<lyra-select>` is no longer
+  silently ignored.
+- A select with exactly one enabled option never exposes `role="combobox"`/opens a listbox at
+  all — see "Single-option auto-commit" above. Testing/automation code that always expects a
+  `role="combobox"` trigger, or that opens the listbox before asserting on a row, needs at least two
+  enabled options to observe the normal dropdown chrome.
 
 ---
 
@@ -588,9 +626,12 @@ Country/language flag image. Flag artwork ships in a **separate, optional peer p
   the small per-flag async hop when you already have the URL at build time, e.g. from
   `import frUrl from '@aceshooting/lyra-flags/flags/fr.svg?url'`. `label` is effectively required
   alongside `src` since there's no `country`/`language` to derive a fallback `alt` from.)
-- `label?: string` (accessible name / `alt` text — **defaults to the bare uppercase *resolved
-  country* code if omitted**, see gotchas)
+- `label?: string` (accessible name / `alt` text — **defaults to a localized, human-readable region
+  name derived from the *resolved country* code via `Intl.DisplayNames` if omitted**, see gotchas)
 - `round: boolean = false` (reflected — circular crop)
+- `detailed: boolean = false` (reflected — requests the pristine, pre-optimization source SVG
+  instead of the default icon-optimized one; a no-op for the majority of codes whose source art was
+  never large enough to need optimizing. Has no effect when `src` is set. See gotchas.)
 
 **Events:** none.
 
@@ -627,11 +668,12 @@ pnpm add @aceshooting/lyra-flags   # required peer — without it, <lyra-flag> r
 - Rendering is async even when the peer *is* installed: `src` resolves after an `import()` +
   resolver call, so there's a brief loading-skeleton window on first paint/attribute change — don't
   assume the `<img>` exists synchronously right after setting `country`/`language`.
-- if `label` is omitted, the accessible name (`alt`) falls back to the **bare uppercase resolved
-  country code** — for `language="en"` that's `"GB"` (the mapped country), not `"EN"` (the language
-  tag itself). A screen reader will typically spell this out letter-by-letter rather than announce a
-  country name. Always pass an explicit `label` (e.g. `"France"`) if the flag conveys real
-  information rather than being purely decorative.
+- if `label` is omitted, the accessible name (`alt`) falls back to a localized region name via
+  `Intl.DisplayNames([navigator.language], { type: 'region' })` (e.g. `"United Kingdom"`) instead of
+  a bare code — for `language="en"` that's derived from `"GB"` (the mapped country), not `"EN"` (the
+  language tag itself). Falls back further to the bare uppercase code if `Intl.DisplayNames` throws
+  for an unrecognized region or isn't available. You can still pass an explicit `label` (e.g.
+  `"France"`) to override the derived name.
 - an invalid `country` (anything not matching the ISO 3166-1 alpha-2 shape, e.g. containing `../`)
   is rejected before it ever reaches the peer's `flagUrl()` resolver — treated the same as an
   unknown/missing flag rather than being passed through. `languageToCountry()`'s region-subtag path
@@ -647,6 +689,13 @@ pnpm add @aceshooting/lyra-flags   # required peer — without it, <lyra-flag> r
   the flags actually requested at runtime (verified with a real Vite build — referencing 2 codes
   shipped ~28 KB total, not all 249). If you already have a flag's URL at build time, `src` skips
   the peer-package round trip (and its loading-skeleton flash) entirely.
+- 65 of `@aceshooting/lyra-flags`' 249 flags (any whose design includes a detailed coat of
+  arms/seal/emblem, e.g. `es`, `pt`, `sv`) ship a second, pristine full-detail source SVG alongside
+  the default icon-optimized one (`flagUrl(code, { variant: 'detailed' })`, or `detailed` on
+  `<lyra-flag>`) — the default variant is the one `country`/`language` resolve to unless `detailed`
+  is set, and is what almost every consumer wants (an icon-scale rendering, ~65% smaller on average
+  for the 65 affected codes, no visible fidelity loss at that scale). `detailed` is a safe no-op for
+  the other 184 codes — same file either way.
 
 ---
 
@@ -745,23 +794,37 @@ KPI/stat card — value + unit + label + optional icon/trend/caption.
 - `goodDirection: 'up'|'down' = 'up'` (attribute `good-direction`) — which trend direction counts
   as "good"; inverts arrow/color polarity for cost/latency/error-rate-style metrics where a
   *decrease* is the win.
-- `rows: StatRow[] = []` (attribute: false) — `StatRow { label: string; value: string }`; rendered as
-  a simple label/value breakdown list (`[part="rows"]`/`[part="row"]`/`[part="row-label"]`/
-  `[part="row-value"]`) beneath the caption, hidden entirely when empty
+- `rows: StatRow[] = []` (attribute: false) — `StatRow { label: string; value: string; exactValue?:
+  string }`; rendered as a simple label/value breakdown list (`[part="rows"]`/`[part="row"]`/
+  `[part="row-label"]`/`[part="row-value"]`) beneath the caption, hidden entirely when empty. A row's
+  optional `exactValue` mirrors the headline `exactValue`/`exact-value` pattern: rendered as a `title`
+  tooltip on that row's `[part="row-value"]` and gives it `tabindex="0"`, independently per row —
+  unset rows are unaffected.
 - `emphasis: boolean = false` (reflected) — visual emphasis (e.g. for a "headline" stat in a group):
   a brand-colored accent edge, orthogonal to the status `variant`; status semantics still win over
   it — `emphasis` only additionally tints `[part="value"]` brand-colored when `variant` is still
   `'neutral'`, never overriding an actual `success`/`warning`/`danger` value color
+- `exactValue: string = ''` (attribute `exact-value`) — rendered as a `title` attribute on
+  `[part="value"]` for a hover tooltip (e.g. `value="$1.2K" exact-value="$1,204.37"`); also gives
+  `[part="value"]` `tabindex="0"` (only when set) so the tooltip is reachable by keyboard focus, not
+  just hover
+- `sub: string = ''` — a secondary line distinct from `caption`, e.g. a comparison-period label,
+  rendered as `[part="sub"]` between the trend pill and the caption; hidden entirely when unset
+- `prose: boolean = false` (reflected) — CSS-only variant that shrinks/lightens `[part="value"]` and
+  hides `[part="unit"]`, for rendering a loading/status message in place of a numeric value
+- `compact: boolean = false` (reflected) — tighter card padding; same convention as `lyra-empty`'s and
+  `lyra-widget`'s `compact`
 
 **Events:** none.
 
 **Slots:** default (leading icon), `caption` (rich caption content — overrides the `caption`
 attribute when slotted content is provided), `spark` (a sparkline, e.g. `<lyra-sparkline
 slot="spark">`, or other compact trend visual — `lyra-stat` only reserves the slot and doesn't
-render one itself)
+render one itself), `sub` (rich sub-line content — overrides the `sub` attribute when slotted content
+is provided)
 
-**CSS parts:** `base`, `icon`, `label`, `value-row`, `value`, `unit`, `trend`, `spark`, `caption`,
-`rows`, `row`, `row-label`, `row-value`
+**CSS parts:** `base`, `icon`, `label`, `value-row`, `value`, `unit`, `trend`, `sub`, `spark`,
+`caption`, `rows`, `row`, `row-label`, `row-value`
 
 **Themeable custom properties:** shared tokens only (`--lyra-color-success/-warning/-danger` drive
 the `variant`-colored value text and up/down trend pill; `--lyra-color-brand` drives `emphasis`'s
@@ -796,9 +859,17 @@ of `rows` — this component only renders and emits intents.
   `priority` progressively hides that column via a `@container` query as `[part='base']` narrows
   (`'low'` hides first, under a ~900px container width; `'medium'` next, under ~640px; both
   breakpoints are fixed in `table.styles.ts`, not themeable tokens), reversible via
-  `[part='reveal-columns-button']` (rendered whenever any column sets a `priority`); `sticky` pins
-  that column's header cell/cells to the inline-start edge (`position: sticky`) while the table
-  scrolls horizontally
+  `[part='reveal-columns-button']`; `sticky` pins that column's header cell/cells to the inline-start
+  edge (`position: sticky`) while the table scrolls horizontally
+- `columnsHidden: boolean = false` (attribute `columns-hidden`, reflected) — computed/read-only: true
+  when a `priority` column is *actually* hidden right now by the `@container` breakpoints above, or
+  `showAllColumns` force-visible mode is currently active. Measured via a `ResizeObserver` on
+  `[part='base']` plus a post-render DOM check, so it settles one render cycle after a `columns`/
+  `rows`/width change lands — poll for the settled value (e.g. `await el.updateComplete;` twice, or
+  `waitUntil()`) rather than assuming a single `updateComplete` covers it. Setting it directly has no
+  lasting effect; it's recomputed on the next render or resize. `[part='reveal-columns-button']` now
+  renders exactly when `columnsHidden` is true — no longer whenever any column merely *declares* a
+  `priority` regardless of whether anything is actually hidden
 - `rows: T[] = []` (attribute: false)
 - `sortKey: string = ''` (attribute `sort-key`)
 - `sortDir: 'asc'|'desc' = 'asc'` (attribute `sort-dir`)
@@ -816,13 +887,14 @@ of `rows` — this component only renders and emits intents.
   button's label once they've been revealed)
 
 **Events:** `lyra-sort` (`detail: { key }`, fired on sortable-header activation), `lyra-row-click`
-(`detail: { row }`), `lyra-load-more` (fired on the "load more" button)
+(`detail: { row }`), `lyra-load-more` (fired on the "load more" button), `lyra-columns-hidden-change`
+(`detail: { hidden: boolean }`, fired only on a real `columnsHidden` transition)
 
 **Slots:** none — content comes entirely from `columns`/`rows`.
 
 **CSS parts:** `base`, `table`, `head`, `header-cell`, `row`, `cell`, `more-button`, `sort-icon` (a
 chevron indicator shown on the active sortable header, rotated per `sortDir`), `reveal-columns-button`
-(shown only when at least one column sets `priority`)
+(shown only when `columnsHidden` is true)
 
 **Themeable custom properties:** `--lyra-table-max-height` (default `none`; controls the scrollable
 body's `max-block-size`).
@@ -997,13 +1069,35 @@ auto-inserted between each adjacent pair.
   regardless — only the effective drag/keyboard clamp bounds (and the rendered `flex-basis`, via a
   native CSS `clamp()` so a constrained panel stays pinned between its px bounds across container
   resizes with no extra `ResizeObserver`) change for a constrained panel.
+- `collapse: 'start'|'end'|'none' = 'none'` (reflected) — opt-in responsive collapse for one panel:
+  `'start'`/`'end'` is a *logical* position (RTL-aware, matching CSS logical properties — the panel at
+  the document's visual leading/trailing edge, not a raw array index). `lyra-split` only owns the
+  width-collapse mechanics/state signaling below; it renders no icon-only UI itself — the collapsing
+  panel's own slotted content is expected to adapt itself (e.g. via its own `@container` query reading
+  the panel's clamped width or `data-collapse-state`, see below).
+- `railWidth: string = '3.5rem'` (attribute `rail-width`) — the fixed CSS length the collapsing panel
+  clamps to in `'rail'` state.
+- `railBreakpoint: number = 640` (attribute `rail-breakpoint`, px) — below this container width (a
+  `ResizeObserver` on `[part='base']`, active only while `collapse !== 'none'`), the collapsing panel
+  switches from its normal drag-resizable percent width to the fixed `railWidth`.
+- `floatBreakpoint: number = 400` (attribute `float-breakpoint`, px) — below this narrower container
+  width, the collapsing panel instead becomes an absolutely-positioned overlay ("floating card") on
+  top of the other pane(s), removed from the normal flex flow; the sibling(s) take the full width.
+
+`collapse`'s three resulting states — `'wide'` (default, today's plain layout) / `'rail'` / `'floating'`
+— are exposed as: a `data-collapse-state` attribute on both the host and the collapsing panel element
+itself (absent for `'wide'`/`collapse="none"`); and the `lyra-split-collapse-change` event below. The
+divider adjacent to the collapsed panel is drag/keyboard-disabled (`aria-disabled="true"`) while
+collapsed. `collapse="none"` (the default) is byte-for-byte identical to pre-collapse-feature behavior.
 
 **Events:** `lyra-resize` (`detail: { sizes }`, fired on every drag step/release **and** every
-keyboard step)
+keyboard step), `lyra-split-collapse-change` (`detail: { state: 'wide'|'rail'|'floating' }`, fired only
+on a real `collapse`-state transition, never on every resize/render)
 
 **Slots:** default (each direct child element is one panel).
 
-**CSS parts:** `base`, `divider`
+**CSS parts:** `base` (`position: relative`, so the `'floating'` state can anchor to it), `divider`
+(carries `aria-disabled="true"` and is drag/keyboard-inert while its adjacent panel is collapsed)
 
 **Themeable custom properties:** shared tokens only.
 
@@ -1063,6 +1157,12 @@ position) survives the transition.
 - `collapsed: boolean = false` (reflected)
 - `expandable: boolean = false` (reflected — shows the fullscreen toggle button)
 - `fullscreen: boolean = false` (reflected)
+- `fullscreenInset: string = ''` (attribute `fullscreen-inset`) — raw CSS `inset` shorthand applied to
+  `[part="base"]` and `[part="backdrop"]` while fullscreen instead of the default
+  `var(--lyra-space-l)` on every side, e.g. `"0 0 0 240px"` to leave a 240px persistent
+  sidebar/toolbar visible during fullscreen
+- `compact: boolean = false` (reflected) — tighter header/body padding, same convention as
+  `lyra-empty`'s `compact`
 
 **Events:** `lyra-collapse-change` (`detail: boolean`, the new `collapsed` state),
 `lyra-fullscreen-change` (`detail: boolean`, the new `fullscreen` state — also fired when fullscreen
@@ -1095,10 +1195,12 @@ to the panel's own focusable content (`actions` slot → collapse/fullscreen but
 matching visual tab order — resolved shadow-piercingly, so a slotted custom element's real
 focusable target inside its own shadow root is found too) so keyboard focus can't escape to page
 content hidden behind the backdrop. Escape or clicking the backdrop exits fullscreen and returns
-focus to whichever button triggered it.
+focus to whichever button triggered it. Set `fullscreen-inset` (e.g. `"0 0 0 240px"`) to reserve
+space for a persistent sidebar/toolbar that should stay visible instead of being covered by the
+fullscreen panel/backdrop — it overrides the default `var(--lyra-space-l)` inset on every side for
+both `[part="base"]` and `[part="backdrop"]`. Set `compact` for tighter header/body padding.
 
 **Known gotchas:**
-- no size/density variant — header and body padding are fixed.
 - a reconnect that preserves the same element instance (e.g. a drag-and-drop reparent) restores the
   scroll lock and the Tab-trap `keydown` listener if `fullscreen` was still `true` across the
   move — `disconnectedCallback`/`connectedCallback` fire back-to-back with no update in between, so
@@ -1327,6 +1429,17 @@ click, or Enter/Space on the focused cell, fires `lyra-cell-click`.
   by `date` (whichever pair matches the active `mode`; the other fields are ignored). Draws a
   stroked ring over the matching cell; an annotation with a `label` also gets its own
   `[part="legend-annotation"]` entry in the legend.
+- `cellText?: (pos: MatrixCellPos | CalendarCellPos, value: number) => string` (attribute: false) —
+  formats the per-cell hover tooltip and keyboard live-region announcement text; receives the cell
+  position (`{ row, col }` in matrix mode, `{ week, weekday }` in calendar mode) and its value.
+  Unset (the default) falls back to the built-in English "Row X, Col Y: value" / "Mon DD: value"
+  template — additive, not breaking.
+- `columnX?: (index: number) => number` (attribute: false, calendar mode only) — overrides the
+  internal week-column x-coordinate formula (`CAL_PAD_LEFT + week * (CAL_CELL + CAL_GAP)`) used
+  consistently across drawing, hit-testing, the focus ring, and month-label positioning, so a
+  consumer can pixel-align this calendar's week columns with a sibling `<lyra-lite-chart>`'s bars
+  (see that component's own `barX`) by supplying the same coordinate function to both. Unset (the
+  default) is the original formula, unchanged.
 
 **Events:** `lyra-cell-click` (fired on click, or Enter/Space on the keyboard-focused cell —
 `detail: { row, col, value }` in matrix mode, `detail: { date, value }` in calendar mode)
@@ -1387,16 +1500,22 @@ color) and `--lyra-space-xs`.
   since `draw()` unconditionally sets an inline `canvas.style.width/height` that wins over it.
   Calendar mode ignores `fit-to-width` entirely — its canvas is always sized from the computed
   `weekCount`.
-- the host itself is unconditionally `role="img"` with a dimensions+range summary `aria-label`
-  (calendar mode: a day-count + range summary instead), same as before — but `[part="canvas"]`
-  inside it is now a real focusable, keyboard-operable, per-cell-interactive control (roving
-  arrow-key focus, `[part="live-region"]` announcements, `lyra-cell-click`). `role="img"` is
-  documented (ARIA) to flatten its subtree to a single image for some assistive tech, which is in
-  tension with a focusable descendant inside it — plausible from the code, unverified against real
-  AT.
+- the host is `role="group"` (not `role="img"`) with a dimensions+range summary `aria-label`
+  (calendar mode: a day-count + range summary instead) — `[part="canvas"]` inside it is a real
+  focusable, keyboard-operable, per-cell-interactive control (roving arrow-key focus,
+  `[part="live-region"]` announcements, `lyra-cell-click`), and `role="img"` is documented (ARIA) to
+  flatten its subtree to a single image for some assistive tech, which conflicted with that
+  focusable descendant — fixed, matching `lyra-lite-chart`/`lyra-word-cloud`'s existing `role="group"`
+  pattern.
 - `NaN`/non-finite cell values in matrix mode are correctly treated as no-data now (alongside `-1`),
   and repeated DPR crossings (moving the window across displays with different pixel ratios) no
   longer leak a `MediaQueryList` listener per crossing — both previously-known issues are fixed.
+- calendar mode's date labels (used by the default `cellText` template and the tooltip/live-region
+  text) now format via the runtime locale (`toLocaleString(undefined, ...)`) instead of a hardcoded
+  `'en'` — fixed. The canvas-drawn axis chrome is now locale-aware too: month labels use
+  `toLocaleString(undefined, ...)` (previously hardcoded `'en'`) and weekday labels are derived via
+  `Intl.DateTimeFormat(undefined, { weekday: 'short' })` (previously a literal English `['', 'Mon',
+  '', 'Wed', '', 'Fri', '']` array) — same sparse every-other-day spacing, just locale-correct text.
 
 ---
 
@@ -1416,7 +1535,7 @@ A force-directed node-link diagram with pan/zoom/drag, built on `d3-force`.
 - `linkDistance: number = 100` (attribute `link-distance` — live-reactive, see gotchas)
 - `minZoom: number = 0.1` (attribute `min-zoom`)
 - `maxZoom: number = 8` (attribute `max-zoom`)
-- `seed?: number` (attribute: false) — when set, seeds each node's initial x/y deterministically
+- `seed?: number` — when set, seeds each node's initial x/y deterministically
   (keyed by node **id**, not array index/order) instead of `forceSimulation()`'s own random start,
   and settles the simulation synchronously instead of animating the settle (same effect
   `prefers-reduced-motion` has, see gotchas)
@@ -1533,6 +1652,11 @@ descendants of the treeitem, matching the WAI-ARIA treeitem pattern's containmen
 - `item: TreeItem` (required, attribute: false)
 - `depth: number = 0`
 - `expanded: boolean = false` (reflected)
+- `activeId: string | null = null` (attribute: false) — the id of the tree's roving-tabindex-focused
+  item, pushed down from `<lyra-tree>`; normally set internally, not by consumers
+- `setSize: number = 1`, `posInSet: number = 1` (attribute: false) — this node's `aria-setsize`/
+  `aria-posinset` values among its siblings, pushed down from `<lyra-tree>`; normally set internally,
+  not by consumers
 
 **Methods:** `expand()`, `collapse()` (each a no-op if already in that state, or a leaf), `select()`
 (fires `lyra-node-select`).
@@ -1667,6 +1791,14 @@ respectively; plus shared `--lyra-space-xs`.
   passthrough is deep-merged with `__proto__`/`constructor`/`prototype` keys skipped unconditionally,
   so a JSON-sourced `config` (e.g. parsed from an API response) can't reach up and pollute
   `Object.prototype` through the merge.
+- lazy-redraw + memoization: an `IntersectionObserver` gates `draw()` — while the host is scrolled
+  off-screen, property changes that would otherwise trigger a Chart.js redraw are skipped (and a
+  single redraw fires once it re-enters the viewport). Independently, a content-signature check
+  (`type`, `labels`, `datasets`, `legend`, `area`, `xLabel`, `yLabel`, `y2Label`, `beginAtZero`,
+  `horizontal`, `stacked`, `config`) skips calling into Chart.js when none of those have actually
+  changed since the last draw (e.g. an unrelated property/state update, or a bare `requestUpdate()`).
+  `refreshTheme()` calls `draw()` directly and is unaffected by either gate — it always redraws, since
+  a theme change isn't reflected in any tracked property.
 
 ---
 
@@ -1691,11 +1823,40 @@ passthrough). Not a subclass of `LyraChart`.
 - `beginAtZero: boolean = true` (attribute `begin-at-zero`)
 - `stacked: boolean = false` — sums each category's bars into one segmented bar instead of grouping
   them side by side; ignored for `type="line"`
+- `tickFormat?: (value: number) => string` (attribute: false) — formats a y-axis tick value for
+  display (e.g. `(v) => \`$${v.toFixed(2)}\`` for currency, or a duration formatter for `"42s"`).
+  Falls back to the built-in "nice numbers" formatter when unset.
+- `layout: 'fit' | 'scroll' = 'fit'` (reflected) — `'fit'` (default) is the original squeeze-the-
+  whole-plot-to-host-width behavior, unchanged. `'scroll'` gives bars a fixed `barWidth` instead: plot
+  content width becomes `categoryCount * barWidth` (can exceed the host's measured width), and
+  `[part='base']` becomes horizontally `overflow-x: auto` so the user scrolls to see every bar at a
+  legible fixed width instead of them compressing as category count grows. Bar type only.
+- `barWidth: number = 32` (attribute `bar-width`, px) — each bar's fixed width in `layout="scroll"`
+  mode; ignored in the default `'fit'` mode.
+- `maxLabels?: number` (attribute `max-labels`, type Number) — decimates which category axis labels
+  actually render *text* when `labels.length > maxLabels` (bars themselves are never decimated, only
+  their axis `<text>` labels): always shows the first and last label, and roughly evenly distributes
+  the rest between them. Works in either `layout` mode. Unset (the default) renders every label,
+  unchanged.
+- `barX?: (index: number) => number` (attribute: false, bar type only) — overrides the internal
+  per-category x-origin formula (`plotX + i * slot`) used by both bars and their axis labels, so a
+  consumer can pixel-align this chart's bars with a sibling `<lyra-heatmap>` calendar's week columns
+  (see that component's own `columnX`) by supplying the same coordinate function to both. Unset (the
+  default) is the original formula, unchanged.
 
 **Events:** `lyra-point-click` — fired when a bar/point is activated (click, or Enter/Space while
 focused). `detail: { datasetIndex: number, index: number, label: string | undefined, value: number
 | null }` — same shape as `lyra-chart`'s `lyra-point-click`.
 
+**Performance:** rendering is `IntersectionObserver`-gated and content-signature-memoized — `render()`
+skips recomputing the grid/marks (and reuses the previous `TemplateResult`) while the host is scrolled
+off-screen, or when none of the content-affecting properties (`type`, `labels`, `datasets`, `legend`,
+`xLabel`, `yLabel`, `beginAtZero`, `stacked`, `layout`, `barWidth`, `maxLabels`, or the measured plot
+size) have changed since the last render. A `tickFormat`/`barX` identity change alone (with everything
+else unchanged) does not force a redraw — in practice both are stable across a component's lifetime,
+and any data change that would make a different output visible already changes `datasets`/`labels`
+too.
+
 **Slots:** none.
 
 **CSS parts:** `base`, `grid-line`, `axis-label`, `axis-title`, `bar`, `line`, `point`, `legend`,
@@ -1999,6 +2160,3734 @@ an extension-only `accept` list.
 
 ---
 
+## `lyra-dialog` / `confirm()`
+
+General-purpose modal/overlay plus a promise-based confirmation helper built on top of it.
+
+### `lyra-dialog`
+
+A modal/overlay: `role="dialog"`, focus-trapped while open, dismissible via Escape or a backdrop
+click, and scroll-locks the document for as long as it's open. Chrome stays minimal — no built-in
+title bar or close button; a consumer supplies a heading and any close affordance itself via the
+default/`footer` slots.
+
+**Properties:**
+- `open: boolean = false` (reflected) — there is no separate `show()`/`hide()` pair; set this (or
+  call `close()`)
+- `label: string = ''` — accessible name used only when no heading is slotted (see below)
+
+**Methods:** `close(reason: DialogCloseReason = 'api'): void` — closes the dialog, emits
+`lyra-dialog-close` with `reason`, and returns focus to whatever had it right before the dialog
+opened. `DialogCloseReason = 'escape' | 'backdrop' | 'api' | string` — `'escape'`/`'backdrop'` are
+emitted by the dialog's own built-in dismiss triggers; any other string is whatever a caller passes
+(e.g. a footer Cancel button calling `dlg.close('cancel')`, or `confirm()`'s own `'confirm'`/`'cancel'`).
+
+**Events:** `lyra-dialog-close` (`detail: DialogCloseReason`) — fired on every dismissal path
+(Escape, backdrop click, or any `close()` call).
+
+**Slots:** default (the dialog body), `footer` (action buttons, rendered in a bottom row, hidden
+entirely when empty)
+
+**CSS parts:** `backdrop` (the full-viewport scrim), `panel` (the dialog panel, `role="dialog"`
+while open), `label` (the invisible label-text element used for `aria-labelledby` when no heading
+is slotted), `body` (wrapper around the default slot), `footer` (wrapper around the `footer` slot)
+
+**Themeable custom properties:** `--lyra-dialog-overlay-color` (default `rgb(0 0 0 / 0.5)` — the
+backdrop scrim color; component-specific since no shared `--wa-*`/`--lyra-*` overlay token exists),
+plus shared tokens `--lyra-space-l/-m/-s`, `--lyra-color-surface/-border`, `--lyra-radius`,
+`--lyra-shadow`.
+
+**Optional peer deps:** none.
+
+```html
+<lyra-dialog id="dlg">
+  <h2>Delete item?</h2>
+  <p>This cannot be undone.</p>
+  <div slot="footer">
+    <button id="cancel">Cancel</button>
+    <button id="confirm">Delete</button>
+  </div>
+</lyra-dialog>
+<script type="module">
+  const dlg = document.getElementById('dlg');
+  dlg.open = true;
+  dlg.addEventListener('lyra-dialog-close', (e) => console.log('closed:', e.detail));
+  document.getElementById('cancel').addEventListener('click', () => dlg.close('cancel'));
+</script>
+```
+
+Accessible name resolution: if a heading element (`h1`–`h6` or `[role="heading"]`) is a *direct
+child* (not inside `slot="footer"`), its text content becomes `aria-label` on the panel. Otherwise,
+when `label` is set, an invisible (`.sr-only`, exposed as the `label` part) element carrying that
+text is rendered inside the panel and `aria-labelledby` points at it instead. Either way `label`
+itself never renders visible chrome — a slotted heading is what a sighted user sees. The heading
+case deliberately uses `aria-label` (a copied string) rather than `aria-labelledby` pointing at the
+heading's `id`, because the heading is light-DOM content while `[part="panel"]` lives in shadow DOM
+and an ID-reference attribute can't resolve across that boundary.
+
+**Known gotchas:**
+- `role="dialog"`/`aria-modal="true"` are only present on `[part="panel"]` while `open` is `true` —
+  inspecting closed markup won't show them.
+- Heading detection only rescans on `slotchange`, not on every render — mutating an already-slotted
+  heading's `textContent` in place (rather than replacing the node) won't retroactively update
+  `aria-label`; set `label` instead for a title that needs to change live.
+- Only *direct* children are scanned for a heading — one nested several layers deep, or inside a
+  slotted custom element's own shadow root, is left to the consumer to label explicitly via `label`.
+- A reconnect that preserves the same element instance (e.g. a drag-and-drop reparent) restores the
+  scroll lock and the Escape/Tab-trap `keydown` listener if `open` was still `true` across the
+  move — `disconnectedCallback`/`connectedCallback` fire back-to-back with no update in between, so
+  `willUpdate()` alone wouldn't otherwise notice.
+- Tab-trap focus order follows the default (body) slot, then the `footer` slot — the same order the
+  flattened tree already tabs through — and is resolved shadow-piercingly, so a slotted custom
+  element's real focusable target inside its own shadow root is found even though the host tag
+  itself isn't a native focusable element.
+
+### `confirm()`
+
+A drop-in async replacement for `window.confirm()`, built on `<lyra-dialog>`.
+
+```ts
+import { confirm } from '@aceshooting/lyra-ui';
+
+const ok = await confirm({
+  title: 'Delete conversation?',
+  description: 'This cannot be undone.',
+  confirmLabel: 'Delete',
+  tone: 'danger',
+});
+if (ok) deleteConversation();
+```
+
+`confirm(options: ConfirmOptions): Promise<boolean>` where
+`ConfirmOptions = { title: string; description?: string; confirmLabel?: string /* = 'Confirm' */; cancelLabel?: string /* = 'Cancel' */; tone?: 'neutral' | 'danger' /* = 'neutral' */ }`.
+
+Resolves `true` only when the confirm button is pressed — Escape, a backdrop click, and the cancel
+button all resolve `false`. Mounts a transient `<lyra-dialog>` on `document.body` for the duration
+of the call and removes it once settled, rather than reusing a persistent page-level region
+(contrast `lyra-toast`'s `toaster.ts`): a confirmation modal has no stacking/queueing concerns —
+only one is ever meant to be open at a time — so a mount-and-remove per call keeps its lifetime
+trivially tied to the returned promise. `title` becomes a slotted `<h2>`, which per `<lyra-dialog>`'s
+own heading-detection also drives the dialog's accessible name; `description`, if provided, becomes
+a slotted `<p>`. `tone: 'danger'` fills the confirm button with `--lyra-color-danger` instead of
+`--lyra-color-brand`, for destructive actions. Confirm/cancel buttons are plain inline-styled
+`<button>` elements (no shared button component exists in this library yet), but every color value
+used is still a `--lyra-*` token reference, never a raw literal.
+
+**Known gotchas:**
+- Every dismissal path (confirm button, cancel button, Escape, backdrop click) funnels through
+  `<lyra-dialog>`'s own `close()`/`lyra-dialog-close` event, so there is exactly one place that
+  resolves the promise and tears the dialog down — a consumer never needs to (and shouldn't) call
+  `.remove()` itself.
+- Both buttons reuse `--lyra-color-on-brand` for their text color, even in the `danger` tone — there
+  is no separate `--lyra-color-on-danger` token, and `--lyra-color-on-brand` happens to be white in
+  both light and dark themes so it reads fine over the danger fill too.
+- Importing `confirm` alone is enough to register `<lyra-dialog>` — `confirm.ts` imports
+  `./dialog.js` for its side effect, so a consumer doesn't need a separate import for the dialog
+  element.
+
+---
+
+## `lyra-tabs`
+
+A tab strip whose panels are direct light-DOM children, each carrying `slot="<id>"` (the panel's
+stable id) and `label="<text>"` (the tab button's text). One named `<slot>` is rendered per distinct
+`slot` name found among the current children — a child with no `label`, or a name with no matching
+child, simply never produces a tab. Implements the WAI-ARIA APG tabs pattern with automatic
+activation: Left/Right (swapped under RTL) move focus *and* selection together, Home/End jump to the
+first/last enabled tab, and a roving `tabindex` follows whichever tab is currently selected.
+
+**Properties:**
+- `active: string = ''` (reflected) — the active tab's `slot`/id; falls back to the first enabled
+  tab whenever the current value doesn't resolve to one (including on every children/attribute
+  change, tracked via a `MutationObserver`)
+
+**Events:** `lyra-tabs-change` (`detail: { tabId: string }`) — fired when the active tab changes via
+click or keyboard. Not fired when `active` self-corrects to a valid tab (initial default, or a tab
+disappearing/becoming disabled underneath the current selection).
+
+**Slots:** default — direct children with `slot="<id>" label="<text>"` (and optionally `disabled`);
+one becomes each tab's panel.
+
+**CSS parts:** `base` (root wrapper around the tablist and panels), `tablist` (the `role="tablist"`
+row of tab buttons), `tab` (a single tab button), `panel` (a single `role="tabpanel"` wrapper, one
+per tab, hidden unless active)
+
+**Themeable custom properties:** shared tokens only — `--lyra-space-s/-m`,
+`--lyra-color-border/-text-quiet/-text/-brand`, `--lyra-transition-fast`, `--lyra-radius`,
+`--lyra-focus-ring-width/-color/-offset`, `--lyra-opacity-disabled`.
+
+**Optional peer deps:** none.
+
+```html
+<lyra-tabs active="general">
+  <div slot="general" label="General">General settings…</div>
+  <div slot="advanced" label="Advanced" disabled>Advanced settings…</div>
+</lyra-tabs>
+<script type="module">
+  document.querySelector('lyra-tabs').addEventListener('lyra-tabs-change', (e) => console.log(e.detail.tabId));
+</script>
+```
+
+**Known gotchas:**
+- Tabs are rebuilt from direct children via a `MutationObserver` watching `childList` plus
+  `attributeFilter: ['slot', 'label', 'disabled']` — not `slotchange` — because a brand-new tab's
+  `slot` name has no matching `<slot>` to fire `slotchange` on until this component has already
+  rendered one for it, and neither `slotchange` nor any Lit lifecycle hook observes a plain
+  attribute edit on a light-DOM child at all.
+- If two children share the same `slot` name, the *first* one wins for the tab button's label
+  (matches native slot assignment: both would render into the one panel, but only one label can back
+  the button).
+- Left/Right are swapped under RTL (read via `internal/rtl.ts`'s `isRtl()`); Up/Down are not used —
+  this is a horizontal strip only.
+
+---
+
+## `lyra-checkbox`
+
+A boolean form control. `role="checkbox"` with an `aria-checked` that can also be `"mixed"`, and a
+visual box/checkmark. Structurally the same idea as `<lyra-switch>` (form-associated via
+`ElementInternals`, click and Space/Enter both toggle) but with checkbox semantics.
+
+**Properties:**
+- `checked: boolean = false` (reflected)
+- `indeterminate: boolean = false` (reflected) — visual-only mixed state; does not affect `checked`,
+  and is cleared back to `false` by any user interaction (click or keyboard), matching native
+  `<input type="checkbox">`
+- `disabled: boolean = false` (reflected)
+- `required: boolean = false` (reflected — enforced via `internals.setValidity()`)
+- `name: string = ''`
+- `value: string = 'on'` — only contributed to form submission while `checked` (a native checkbox
+  submits nothing at all, not even an empty string, while unchecked)
+
+**Events:** `lyra-change` (`detail: { checked: boolean }`) — fired on a user toggle (click or
+Space/Enter); not fired for a programmatic `.checked` assignment.
+
+**Slots:** default — label text, rendered next to the box. Clicking it toggles the checkbox, the
+same as clicking a native checkbox's associated `<label>`. If left empty, set `aria-label` on the
+host so the control still has an accessible name.
+
+**CSS parts:** `base` (the whole interactive control, `role="checkbox"`), `box` (the small square
+showing the checkmark/indeterminate dash), `checkmark` (the checkmark or indeterminate-dash glyph),
+`label` (wrapper around the default slot)
+
+**Themeable custom properties:** shared tokens only — `--lyra-space-s`, `--lyra-icon-button-size`,
+`--lyra-color-border/-surface/-on-brand/-brand/-text`, `--lyra-radius`, `--lyra-transition-fast`,
+`--lyra-focus-ring-width/-color/-offset`, `--lyra-opacity-disabled`.
+
+**Optional peer deps:** none.
+
+```html
+<lyra-checkbox name="terms" required>Accept the terms and conditions</lyra-checkbox>
+<script type="module">
+  document
+    .querySelector('lyra-checkbox')
+    .addEventListener('lyra-change', (e) => console.log(e.detail.checked));
+</script>
+```
+
+Form-associated via a directly-attached `ElementInternals` (not the shared `FormAssociated` mixin,
+whose `value` accessor assumes a plain string default flow) with its own hand-rolled
+`updateValidity()` — same shape as `<lyra-combobox>`'s and `<lyra-switch>`'s direct-`ElementInternals`
+handling.
+
+**Known gotchas:**
+- `formResetCallback()` restores `checked` to whatever the declarative `checked` attribute parsed to
+  at first connect — captured once via a one-shot flag (not from `attributeChangedCallback` alone,
+  since `checked` reflects and that would wrongly re-capture on every later user toggle). A later
+  `el.checked = true` assignment never redefines the reset default.
+- `indeterminate` is visual-only and silently clears on any user click/keypress — a consumer relying
+  on it staying `true` after a user interacts with the box will be surprised.
+- The rendered `aria-label` is copied from the host's own `aria-label` attribute at render time; if
+  neither that nor slotted label text is present, the control has no accessible name.
+
+---
+
+## `lyra-switch`
+
+A boolean toggle-switch form control. `role="switch"` with `aria-checked` read as an on/off state
+rather than checked/unchecked, and no indeterminate state. Structurally the same idea as
+`<lyra-checkbox>` (form-associated via `ElementInternals`, click and Space/Enter both toggle).
+
+**Properties:**
+- `checked: boolean = false` (reflected)
+- `disabled: boolean = false` (reflected)
+- `required: boolean = false` (reflected — enforced via `internals.setValidity()`)
+- `name: string = ''`
+- `value: string = 'on'` — only contributed to form submission while `checked`
+
+**Events:** `lyra-change` (`detail: { checked: boolean }`) — fired on a user toggle (click or
+Space/Enter); not fired for a programmatic `.checked` assignment.
+
+**Slots:** default — label text, rendered next to the track. Clicking it toggles the switch, the
+same as clicking a checkbox's associated `<label>`. If left empty, set `aria-label` on the host so
+the control still has an accessible name.
+
+**CSS parts:** `base` (the whole interactive control, `role="switch"`), `track` (the pill-shaped
+background), `thumb` (the circular knob that slides across the track), `label` (wrapper around the
+default slot)
+
+**Themeable custom properties:** `--track-inline-size` (default `2.25rem`), `--track-block-size`
+(default `1.25rem`), `--thumb-offset` (default `2px`) — component-local geometry knobs, set on
+`:host`, since a fully-rounded pill/thumb needs a radius well past the shared `--lyra-radius`
+default — plus shared tokens `--lyra-space-s`, `--lyra-color-border/-brand/-surface/-text`,
+`--lyra-transition-fast`, `--lyra-focus-ring-width/-color/-offset`, `--lyra-opacity-disabled`.
+
+**Optional peer deps:** none.
+
+```html
+<lyra-switch name="notifications" checked>Enable notifications</lyra-switch>
+<script type="module">
+  document
+    .querySelector('lyra-switch')
+    .addEventListener('lyra-change', (e) => console.log(e.detail.checked));
+</script>
+```
+
+Form-associated the same way as `<lyra-checkbox>`: a directly-attached `ElementInternals` with a
+hand-rolled `updateValidity()`, not the shared `FormAssociated` mixin. The thumb animates the
+logical `inset-inline-start` property (not a physical `transform: translateX()`), so the slide
+direction mirrors correctly under `dir="rtl"`.
+
+**Known gotchas:**
+- `formResetCallback()` restores `checked` to the value captured from the declarative `checked`
+  attribute at first connect (same one-shot-flag capture as `<lyra-checkbox>`) — a later `.checked =
+  true` property assignment never redefines what `form.reset()` restores to.
+- The rendered `aria-label` is copied from the host's own `aria-label` attribute at render time; with
+  neither that nor slotted label text, the control has no accessible name.
+
+---
+
+## `lyra-json-viewer`
+
+A collapsible, copyable tree view for an arbitrary JSON-serializable value (object, array, string,
+number, boolean, null, or `undefined`). Serves as a fallback renderer wherever a raw payload needs
+inspecting without a bespoke view. Expand/collapse state is keyed by structural path (not object
+identity), so it survives a `data` reassignment that keeps the same shape — e.g. a streaming result
+being patched in place.
+
+**Properties:**
+- `data: unknown` (attribute `false` — property-only, not settable via an HTML attribute)
+- `collapsedDepth?: number` (attribute `collapsed-depth`) — nodes at or beyond this nesting depth
+  (root = `0`) start collapsed; omitted/`undefined` means nothing auto-collapses
+- `maxHeight: string = ''` (attribute `max-height`) — a CSS length (e.g. `"20rem"`); once set, the
+  viewer scrolls internally past this height instead of growing the page
+- `copyable: boolean = false` (reflected) — shows copy-to-clipboard affordances: one for the whole
+  value, plus one per node
+- `search: string = ''` — case-insensitive substring match against keys/values; matches are
+  highlighted and their ancestors auto-expanded
+
+**Events:** `lyra-copy` (`detail: { text: string }`) — fired by the top-level copy button or a
+per-node one. Fires even when `navigator.clipboard` silently failed or is unavailable (insecure
+context, older browser, a stubbed-out test environment), so a consumer can still observe copy
+*intent*.
+
+**Slots:** none — the tree is rendered entirely from `data`.
+
+**CSS parts:** `base` (root scroll container, respects `max-height`), `toolbar` (wrapper around the
+top-level copy button, only rendered when `copyable`), `tree` (wrapper around the rendered node
+tree), `key` (an object property key or array index label), `value` (a primitive value's text —
+carries `data-type` of `string`/`number`/`boolean`/`null`/`undefined` for per-type coloring, and
+`data-match` while it matches `search`), `bracket` (a `{`, `}`, `[`, or `]` delimiter), `toggle` (a
+container node's expand/collapse button; hidden but present for row alignment on leaf/empty nodes),
+`copy-button` (a copy-to-clipboard button — the top-level one in `toolbar`, or a per-node one; only
+rendered when `copyable`)
+
+**Themeable custom properties:** `--lyra-json-viewer-max-height` (default `none` — grows with content
+until `max-height` is set), `--lyra-json-viewer-font` (default `ui-monospace, SFMono-Regular, Menlo,
+Consolas, monospace` — component-specific since no shared monospace token exists), plus shared tokens
+`--lyra-color-border/-surface/-text/-text-quiet/-brand/-brand-quiet/-success/-warning/-warning-quiet`,
+`--lyra-radius`, `--lyra-space-xs/-s/-l`, `--lyra-focus-ring-width/-color/-offset`,
+`--lyra-transition-fast`.
+
+**Optional peer deps:** none.
+
+```ts
+import { html } from 'lit';
+import '@aceshooting/lyra-ui/components/json-viewer/json-viewer.js';
+
+html`<lyra-json-viewer .data=${apiResponse} copyable max-height="24rem" search=${query}></lyra-json-viewer>`;
+```
+
+```html
+<lyra-json-viewer copyable max-height="24rem"></lyra-json-viewer>
+<script type="module">
+  document.querySelector('lyra-json-viewer').data = { hello: 'world', items: [1, 2, 3] };
+</script>
+```
+
+**Known gotchas:**
+- `data` is property-only (`attribute: false`) — it must be set via `.data = ...` or a lit-html `.data=${...}`
+  binding, never as a plain HTML attribute.
+- Search highlighting auto-expands only the *ancestors* of a match, not the whole tree — a
+  non-matching sibling subtree elsewhere stays collapsed (or expanded) exactly as it already was.
+- An explicit per-node expand/collapse (from clicking a node's `toggle` button) permanently overrides
+  both `collapsedDepth` and any search-driven auto-expand for that path, until `data` is reassigned
+  with a different shape.
+- Per-node copy buttons call `stopPropagation()` on click so clicking one doesn't also toggle the
+  row's expand/collapse state.
+
+---
+
+## `lyra-live-region` (+ internal `Announcer`)
+
+A throttled screen-reader announcement helper, split into a DOM-free coalescing engine
+(`internal/announcer.ts`'s `Announcer` class) and a real custom element that wraps it.
+
+### Internal: `Announcer` (`internal/announcer.ts`)
+
+Not a custom element — pure timing/coalescing logic with no DOM dependency, composed by
+`<lyra-live-region>` (below) and intended for reuse by any other component that needs throttled
+announcements (a stream-status indicator, a tool-call chip's status transitions, a chat message's
+streaming state).
+
+Streaming UIs (token-by-token chat responses, progress ticks, etc.) naturally produce far more
+candidate announcements than a screen-reader user can usefully absorb — reading every incremental
+chunk aloud is spam, not information. `Announcer` collapses a burst of `announce()` calls arriving
+within `throttleMs` of the *first* call in that burst down to a single trailing-edge flush of the
+latest text: superseded intermediate text is dropped outright, never queued or concatenated.
+
+- `new Announcer(options: AnnouncerOptions)` where
+  `AnnouncerOptions = { throttleMs?: number /* = 500 */; onFlush: (text: string) => void }`.
+- `announce(text: string, options?: AnnounceOptions)` where `AnnounceOptions = { force?: boolean }` —
+  queues `text`, overwriting whatever an earlier call in the same burst queued. Only the *first*
+  call of a burst schedules the flush timer, so the deadline stays anchored to that first call
+  rather than being pushed back by every subsequent call. `{ force: true }` bypasses any
+  in-progress window and flushes immediately, so a terminal message (e.g. "response complete") is
+  never swallowed mid-burst.
+- `cancel()` — drops any pending (not yet flushed) text without invoking `onFlush`.
+- `pendingText: string | undefined` — the latest text awaiting flush, if a burst is in progress.
+- `isPending: boolean` — whether a flush is currently scheduled.
+- `throttleMs` — a plain public field, safe to change between bursts; a flush already scheduled
+  keeps the deadline it was scheduled with.
+
+### `lyra-live-region`
+
+A visually-hidden ARIA live region that throttles and coalesces announcements instead of relaying
+every call verbatim, by composing an internal `Announcer`. A consumer typically mounts one
+`<lyra-live-region>` per page/surface (much like `<lyra-toast>` is one region per placement) and
+keeps a reference to call `announce()` from application code or a parent component.
+
+**Properties:**
+- `mode: 'polite' | 'assertive' = 'polite'` (reflected) — `'polite'` renders `role="status"` +
+  `aria-live="polite"` (waits for the user to be idle); `'assertive'` renders `role="alert"` +
+  `aria-live="assertive"` (interrupts)
+- `throttleMs: number = 500` (attribute `throttle-ms`) — the coalescing window; see `Announcer`
+  above
+
+**Methods:** `announce(text: string, options?: AnnounceOptions): void` — queues `text` for
+announcement through the internal `Announcer`; `{ force: true }` bypasses the current throttle
+window and flushes immediately.
+
+**Events:** none.
+
+**Slots:** none.
+
+**CSS parts:** `region` — the visually-hidden element carrying `role`/`aria-live`.
+
+**Themeable custom properties:** none component-specific — the region is hidden via the shared
+`.sr-only` helper class (`internal/a11y.ts`), not tokenized CSS.
+
+**Optional peer deps:** none.
+
+```html
+<!-- once, near the root of a page/surface -->
+<lyra-live-region id="live" mode="polite"></lyra-live-region>
+<script type="module">
+  const live = document.getElementById('live');
+  // streaming tokens: fine to call on every chunk, only the trailing state lands
+  live.announce(`${partialText} …`);
+  // stream finished: always announced, even mid-throttle-window
+  live.announce('Response complete', { force: true });
+</script>
+```
+
+A parent Lit component would instead hold the reference via `@query('lyra-live-region')`.
+
+**Known gotchas:**
+- Re-announcing text identical to what was last written is special-cased: screen readers announce a
+  live region only on text-content *change*, so the component clears `textContent` first and
+  re-sets it on the next animation frame (not the same tick, which can coalesce into nothing ever
+  appearing to change) to give assistive tech a real empty-to-populated transition to observe.
+- The region's DOM is tracked outside Lit's own template bindings (`write()` mutates
+  `regionEl.textContent` directly) — an `announce()`/flush landing before `firstUpdated()` has run
+  (e.g. a consumer creates, appends, and calls `announce()` synchronously) is buffered and applied
+  on the next `firstUpdated()` rather than dropped.
+- `disconnectedCallback()` cancels any pending (unflushed) announcement and any in-flight re-announce
+  animation-frame callback — an element removed mid-throttle-window silently drops whatever was
+  queued.
+- Changing `throttle-ms` updates the live `Announcer`'s window immediately, but a flush already
+  scheduled under the old window keeps the deadline it was scheduled with.
+
+---
+
+## `lyra-markdown`
+
+Sanitized Markdown-to-HTML rendering (GFM tables, fenced code blocks, links, blockquotes) built on
+two optional peer dependencies — `marked` (parsing) and `dompurify` (sanitizing) — both lazy-loaded
+independently via `markdown-loader.ts`'s `loadMarkdownDeps()` on first connect, cached per page the
+same way `chart-loader.ts`/`map-loader.ts` cache their load promise so every `<lyra-markdown>`
+instance on a page shares one load. `heading`/`code`/`blockquote`/`table`/`link` tokens are rendered
+through a `marked` renderer override that injects `part="..."` attributes directly into the produced
+HTML in a single pass (no second DOM walk after insertion).
+
+**Properties:**
+- `content: string = ''` — the Markdown source to render
+- `sanitize: boolean = true` — sanitize `marked`'s HTML output with DOMPurify before rendering
+- `gfm: boolean = true` — GitHub-flavored Markdown (tables, strikethrough, autolinks, task lists)
+- `linkTarget: string = '_blank'` (attribute `link-target`) — `target` applied to every rendered
+  `<a>`; `rel="noopener noreferrer"` is always added alongside it regardless of this value
+- `internalLinkPrefix: string = ''` (attribute `internal-link-prefix`) — when set, a rendered link
+  whose `href` *attribute* (not the browser-resolved `.href` property) starts with this prefix is
+  intercepted on click and reported via `lyra-link-click` instead of navigating; empty (the default)
+  means every link is treated as external
+- `streaming: boolean = false` (reflected) — forward-compatible hint for a future streaming renderer
+  expected to build on this component (coalescing partial tokens as they arrive); setting it has no
+  rendering effect yet, it only lets a consumer already target `lyra-markdown[streaming]` in CSS
+
+**Events:** `lyra-link-click` (`detail: { href: string, internal: true }`, fired — with the click
+prevented — when a rendered link's `href` starts with `internal-link-prefix`; ordinary external
+links navigate normally and never fire this), `lyra-render-error` (`detail: { error: unknown }`,
+fired whenever rendering falls back to plain text — see the fallback matrix below)
+
+**Slots:** none — content comes from the `content` property, not light-DOM children.
+
+**CSS parts:** `content` (the wrapper around the rendered or plain-text-fallback output), `heading`
+(every rendered `<h1>`–`<h6>`), `code-block` (every rendered fenced/indented `<pre>`), `link` (every
+rendered `<a>`), `table` (every rendered `<table>`), `blockquote` (every rendered `<blockquote>`)
+
+**Themeable custom properties:** `--lyra-markdown-font-mono` (default `ui-monospace, SFMono-Regular,
+Menlo, Consolas, monospace` — the code/code-block font; component-specific since no shared
+`--wa-*`/`--lyra-*` monospace token exists), plus shared tokens `--lyra-space-xs/-s/-m/-l`,
+`--lyra-color-brand-quiet`, `--lyra-color-brand`, `--lyra-color-border`, `--lyra-color-text-quiet`,
+`--lyra-radius`.
+
+**Optional peer deps:** `marked`, `dompurify` (both lazy-loaded via `markdown-loader.ts`'s
+`loadMarkdownDeps()`, mirroring `chart-loader.ts`'s two-independent-optional-peers shape). Each half
+is loaded and caught independently — a consumer who installs only `marked` and explicitly sets
+`sanitize="false"` (so `dompurify` is never needed) is a valid, supported combination.
+
+```html
+<lyra-markdown
+  content="# Report&#10;&#10;See the [setup guide](/docs/setup) for details."
+  internal-link-prefix="/docs/"
+></lyra-markdown>
+<script>
+  document.querySelector('lyra-markdown').addEventListener('lyra-link-click', (e) => {
+    router.navigate(e.detail.href);
+  });
+</script>
+```
+
+Rendering never ships unsanitized or broken markup silently. If `marked` fails to load, or throws
+while parsing malformed input, the component falls back to plain text (`white-space: pre-wrap`, no
+HTML parsing at all — the raw `content` string itself) and fires `lyra-render-error`. If `sanitize`
+is `true` (the default) and `dompurify` fails to load, the component *also* falls back to plain text
++ `lyra-render-error` — it never renders `marked`'s raw HTML output when sanitization was requested
+(or defaulted to) but is unavailable, even though `marked` itself loaded fine. If `sanitize` is
+explicitly `false`, `marked`'s raw output renders as-is regardless of whether `dompurify` is
+installed. While the optional peers are still resolving, the host carries `aria-busy="true"` (set/
+cleared in `updated()` based on whether the deps have loaded) and shows the same plain-text fallback
+rendering — there's no separate loading skeleton, since the un-rendered Markdown source is already
+legible text in the meantime.
+
+**Known gotchas:**
+- a malformed percent-escape or lone UTF-16 surrogate in a link's raw `href` makes the internal
+  `encodeURI`-based validity guard throw, silently dropping just that anchor (the link text still
+  renders, with no `href`) — mirrors `marked`'s own default `link()` renderer's defensive behavior.
+- `target` is not in DOMPurify's default attribute allowlist (unlike `part`/`rel`/`class`, which
+  already are), so sanitization is called with `ADD_ATTR: ['target']` — without that, every rendered
+  link's `target` would be silently stripped by sanitization even though the anchor itself survives.
+- a fresh `marked.Marked()` instance (with a fresh renderer) is built on every single parse rather
+  than cached, specifically so the renderer's `link()` override always closes over the *current*
+  `linkTarget` — `marked`'s `.use()` otherwise persists whatever renderer it was given for the
+  instance's lifetime, which would go stale if `linkTarget` changed after a cached instance's first use.
+- `internal-link-prefix` matching compares against the raw `href` *attribute*, not the resolved
+  `.href` IDL property (always an absolute URL in the browser) — a prefix like `/docs/` matches a
+  relative markdown link but would never match against the resolved property.
+- rendered output goes through `unsafeHTML`; with `sanitize="false"` the component renders whatever
+  HTML `marked` produces from `content` completely unsanitized, so untrusted `content` must never be
+  paired with `sanitize="false"`.
+
+---
+
+## `lyra-chat-message`
+
+A role-based message bubble *shell* for a chat/agent conversation surface. It renders none of the
+message content itself — the default slot carries whatever a consumer wants to display (plain text,
+a `<lyra-markdown>`, a custom template, anything) and this component only supplies the surrounding
+chrome: alignment/coloring by `role`, an avatar/badges header row, an optional collapse toggle, an
+attachments strip, and a status-aware footer (a live-updating status dot + text, the formatted
+`timestamp`, a built-in retry affordance for `status="failed"`, and an `actions` slot for everything
+else). No built-in copy button is rendered — slot a copy control into `actions` and fire `lyra-copy`
+from it if you want one (matching `<lyra-json-viewer>`'s copy-affordance event name for anything
+listening at the conversation-surface level).
+
+**Properties:**
+- `role: ChatMessageRole = 'assistant'` (`'user' | 'assistant' | 'system'`) — reflects to
+  `data-role`, **not** the bare `role` attribute (those role strings aren't valid ARIA role tokens
+  and reflecting to `role` would collide with the element's own ARIA role); a plain `role="..."`
+  attribute set directly in markup is ignored entirely
+- `status: ChatMessageStatus = 'sent'` (`'sending' | 'sent' | 'failed' | 'streaming'`, reflected) —
+  drives the footer's status dot/text, `status="failed"`'s danger treatment on the bubble, and the
+  built-in retry button
+- `timestamp?: Date | string` (attribute: false) — accepts a `Date` or anything `new Date()` can
+  parse; invalid input is treated the same as unset (no timestamp rendered)
+- `formatTimestamp?: (date: Date) => string` (attribute: false) — overrides the default
+  `hour:minute` (`Intl.DateTimeFormat`, runtime locale) rendering of `timestamp`
+- `collapsible: boolean = false` (reflected) — shows the built-in collapse/expand toggle in the header
+- `collapsed: boolean = false` (reflected) — whether the message body is hidden; effective whenever
+  set, independent of `collapsible` (which only controls whether the toggle button itself is
+  rendered) — mirrors `lyra-widget`'s identical `collapsible`/`collapsed` pair
+
+**Events:** `lyra-retry` (no detail payload; fired by the built-in retry button, only rendered when
+`status="failed"`), `lyra-collapse-toggle` (`detail: boolean`, the new `collapsed` state — fired when
+the user activates the built-in collapse button)
+
+**Slots:** default (the message body), `avatar` (an avatar/icon for the message author), `badges`
+(small status/metric chips — e.g. token count, latency, model name — entirely app-supplied), `actions`
+(action controls such as copy/retry, rendered at the end of the footer), `attachments` (file/image
+attachment chips, rendered below the message body)
+
+**CSS parts:** `bubble`, `header` (hidden entirely when nothing is in it), `avatar`, `badges`,
+`collapse-button` (only rendered when `collapsible`), `body` (hidden while `collapsed`),
+`attachments`, `footer` (hidden entirely when nothing is in it), `status-indicator` (a small
+decorative `aria-hidden` dot, absent while `status="sent"`), `status-text` (the visible text twin of
+`status-indicator`), `timestamp`, `retry-button` (only rendered when `status="failed"`), `actions`
+
+**Themeable custom properties:** `--lyra-chat-message-max-width` (default `80%` — the bubble's max
+inline size; component-specific, no shared width token exists), plus shared tokens
+`--lyra-space-xs/-m`, `--lyra-color-border`, `--lyra-color-surface`, `--lyra-color-brand-quiet`,
+`--lyra-color-brand`, `--lyra-color-text-quiet`, `--lyra-color-danger`, `--lyra-color-danger-quiet`,
+`--lyra-radius`, `--lyra-icon-button-size`, `--lyra-focus-ring-*`, `--lyra-transition-fast`.
+
+**Optional peer deps:** none. Internally renders a `<lyra-live-region>` (a first-party sibling
+component, auto-imported alongside this one, not an npm peer) for the status-transition
+announcements described below.
+
+```html
+<lyra-chat-message data-role="assistant" status="streaming">
+  <span slot="avatar">🤖</span>
+  <span slot="badges">gpt-5.4 · 1.2s</span>
+  <lyra-markdown content="Here's what I found…"></lyra-markdown>
+  <button slot="actions">Copy</button>
+</lyra-chat-message>
+<script>
+  document.querySelector('lyra-chat-message').addEventListener('lyra-retry', () => resend());
+</script>
+```
+
+Accessibility of `status`: the current status is always available as plain visible text
+(`[part="status-text"]`), never color alone. A transition *to* `"failed"`, or *from* `"streaming"` to
+`"sent"` (a stream finishing), is additionally announced through the internal `<lyra-live-region>` —
+`"failed"` announces assertively (`"Message failed to send."`), a streaming→sent completion announces
+politely (`"Message complete."`) — so a screen-reader user not currently focused on this message
+still learns about it. No other status transition is announced (e.g. `streaming`→`sending`, or
+`sending`→`sent` without having passed through `streaming`, produce no announcement). This differs
+from `<lyra-typing-indicator>`'s deliberately simpler `role="status"` approach, appropriate there
+since that component only ever announces once (its own mount); this component's `status` can flip
+between several values across a single element's lifetime.
+
+**Known gotchas:**
+- mounting a message with `status="failed"` (or any other non-`"sent"` status) already set does
+  **not** announce anything — only a genuine *later* transition (`changed.get('status') !==
+  undefined`, i.e. not the very first update) triggers the live-region announcement.
+- `lyra-retry` fires with no detail payload at all (`undefined`), not e.g. `{ status: 'failed' }`.
+- the header/footer/avatar/badges/attachments/actions wrappers are shown/hidden via the `hidden`
+  attribute, not conditional templating. Whether each slot currently has content is checked once via
+  a light-DOM children scan on the very first update (`willUpdate`, gated on `!this.hasUpdated`) and
+  thereafter only via each slot's own `slotchange` listener — content added directly with
+  `appendChild` after first paint still triggers native `slotchange`, so this works transparently,
+  but any code that manually re-parents already-slotted nodes without a real slot-assignment change
+  won't refresh the corresponding wrapper's visibility.
+- `role` intentionally reflects to `data-role`; CSS or selectors that key off role must target
+  `[data-role="user"]` etc., not `[role="user"]`.
+
+---
+
+## `lyra-typing-indicator`
+
+A purely presentational "assistant is responding" presence cue — no events, no interactivity. A
+consumer mounts it while a response is being generated and removes (or hides) it once real content
+arrives. Three visual variants share one component rather than three separate tags, since callers
+pick between them along a single axis (how the surrounding surface wants the cue to read) and
+nothing else about the component differs: `dots` (default, three dots with a staggered bounce — the
+classic "typing…" affordance for a standalone status line), `pulse` (a single breathing dot, a
+quieter cue for a tight space, e.g. next to an avatar), `cursor` (a blinking vertical bar, meant to
+sit inline at the tail end of streamed text still being appended to).
+
+**Properties:**
+- `variant: TypingIndicatorVariant = 'dots'` (`'dots' | 'pulse' | 'cursor'`, reflected)
+- `label: string = 'Thinking…'` — the accessible name, exposed via `role="status"`; not re-announced
+  on every animation frame, only on mount and on any later change to this property
+- `size: TypingIndicatorSize = 'md'` (`'sm' | 'md'`, reflected) — compact sizing for dense layouts
+
+**Events:** none — purely presentational.
+
+**Slots:** none.
+
+**CSS parts:** `base` (the decorative, `aria-hidden`, wrapper around the animated shape), `dot`
+(each of the three dots in the `dots` variant), `pulse` (the single pulsing dot in the `pulse`
+variant), `cursor` (the blinking bar in the `cursor` variant)
+
+**Themeable custom properties:** `--lyra-typing-dot-size` (default `0.5rem`, `0.375rem` at
+`size="sm"`), `--lyra-typing-gap` (default `0.25rem`, `0.1875rem` at `size="sm"`),
+`--lyra-typing-cursor-width` (default `0.125rem`, `0.09375rem` at `size="sm"`),
+`--lyra-typing-cursor-height` (default `1em`, unaffected by `size`) — all component-specific; plus
+the shared `--lyra-transition-base` token, used as each variant's full `animation:` shorthand
+(duration + timing-function together) since it drives a continuous ambient loop rather than a
+discrete state flip (which would instead use `--lyra-transition-fast`).
+
+**Optional peer deps:** none.
+
+```html
+<lyra-typing-indicator label="Assistant is responding…"></lyra-typing-indicator>
+<lyra-typing-indicator variant="pulse" size="sm"></lyra-typing-indicator>
+<lyra-typing-indicator variant="cursor"></lyra-typing-indicator>
+```
+
+Accessibility: since this indicator typically mounts and unmounts around a real generation lifecycle
+(appears when a response starts, disappears once one arrives) rather than emitting a stream of
+updates of its own, it does **not** route through `<lyra-live-region>`/the internal `Announcer` —
+that machinery exists to coalesce many rapidly-changing announcements into one, and there is only
+ever a single announcement here: the mount itself. `role="status"` plus an accessible name derived
+from `label` is set both as `aria-label` on the host *and* as a visually-hidden text node
+(`.sr-only`) in the shadow tree, so the name survives even if only one of the two is picked up by a
+given assistive-tech/browser pairing. The animated shape itself is `aria-hidden="true"` — it's
+decorative; `label` is the entire accessible content, nothing narrates individual animation frames.
+
+**Known gotchas:**
+- under `prefers-reduced-motion: reduce`, every variant collapses to its plain, fully-visible resting
+  state (`opacity: 1`, no transform, `animation: none !important`) rather than freezing on whatever
+  frame the animation happened to be on — notably relevant for `cursor`, which would otherwise risk
+  freezing on its invisible ("off") blink half.
+- the two dot-bounce stagger delays (`60ms`, `120ms`) are fixed literals, not `calc()`-derived
+  fractions of `--lyra-transition-base` — that token is a *compound* `duration timing-function` value
+  (like every `transition:`/`animation:` shorthand token in this library), so it can't be decomposed
+  arithmetically; the two delays just approximate a third and two-thirds of the token's own default
+  duration.
+- `size="sm"` shrinks the dot size, gap, and cursor width, but **not** `--lyra-typing-cursor-height`
+  (still `1em` at any size) — the cursor bar's height is meant to track surrounding text size via
+  `1em`, not the component's own `size` property.
+
+---
+
+## `lyra-tool-call-chip`
+
+A compact inline pill representing one tool/function call an agent made mid-conversation, e.g.
+`web_search: Searching web…` with a `running` spinner. First-party invention (no Web Awesome
+equivalent). It owns no detail surface of its own — activating it (click or Enter/Space while
+focused) only fires `lyra-tool-chip-select`; a consumer wires that to opening a
+`<lyra-tool-result-dialog>` (or anything else) at the call site, keeping the chip reusable wherever
+a compact call summary is useful, with or without a detail surface behind it.
+
+**Properties:**
+- `name: string = ''` — the tool/function name, e.g. `web_search`
+- `category: string = ''` — optional grouping label, e.g. `research`
+- `status: 'pending'|'running'|'success'|'error'|'denied' = 'pending'` (reflected) — drives the
+  glyph, accent color, and `status-text`; same status vocabulary as `<lyra-tool-result-dialog>` so a
+  call's chip and its detail dialog always agree
+- `summary: string = ''` — short human-readable status text, e.g. `Searching web…`
+- `durationMs?: number` (attribute `duration-ms`) — how long the call took, in milliseconds; the
+  `duration` part is omitted entirely when unset
+- `icon: string = ''` — literal icon hint (e.g. an emoji) rendered when the `icon` slot is empty;
+  ignored once anything is assigned to `slot="icon"`
+- `callId: string = ''` (attribute `call-id`) — unique identifier for this invocation, echoed back
+  in `lyra-tool-chip-select`'s detail so a listener can correlate the click with the call it fired for
+
+**Events:** `lyra-tool-chip-select` (`detail: { name: string; callId: string }`) — fired on click or
+Enter/Space activation of the pill.
+
+**Slots:** default (rich tooltip/detail content — e.g. the tool's raw arguments or a short preview —
+shown in a floating tooltip on hover/focus; nothing renders at all, no hover affordance, when this
+slot is empty), `icon` (overrides the built-in per-status glyph entirely via native slot-fallback
+content — assigned content wins; otherwise the `icon` prop is rendered as a literal hint; otherwise
+the built-in glyph for the current `status` is used)
+
+**CSS parts:** `base` (the clickable `<button>`), `icon`, `label` (wrapper around `category`, `name`,
+`summary`), `category`, `name`, `summary`, `meta` (wrapper around `status-text` and `duration`),
+`status-text`, `duration`, `tooltip` (the floating detail popup, only meaningful while open)
+
+**Themeable custom properties:** no component-specific custom properties (per-status accent/
+background/border are internal `--lyra-tool-call-chip-*` variables swapped by `:host([status])`
+rules, not part of the public theming API); shared tokens referenced: `--lyra-color-text-quiet`,
+`--lyra-color-surface`, `--lyra-color-border`, `--lyra-color-brand`/`-brand-quiet`,
+`--lyra-color-success`/`-success-quiet`, `--lyra-color-danger`/`-danger-quiet`,
+`--lyra-color-warning`/`-warning-quiet`, `--lyra-color-text`, `--lyra-space-xs/-s/-m`, `--lyra-radius`,
+`--lyra-shadow`, `--lyra-focus-ring-*`, `--lyra-transition-fast`.
+
+**Optional peer deps:** none.
+
+```html
+<lyra-tool-call-chip
+  name="web_search"
+  category="research"
+  status="running"
+  summary="Searching web…"
+  duration-ms="820"
+  call-id="call_123"
+  @lyra-tool-chip-select=${(e) => openDetail(e.detail.callId)}
+>
+  <pre slot="icon" style="display:none"></pre>
+  <code>{"query": "lyra ui components"}</code>
+</lyra-tool-call-chip>
+```
+
+The default slot's tooltip is positioned with the same `internal/positioner.js` `place()` helper
+`<lyra-combobox>` uses for its listbox (`placement: 'top-start'`), and appears/disappears instantly
+on hover/focus/blur/mouseleave with no fade transition and no "pointer moved into the tooltip"
+tracking — it's documented as read-only preview content, not an interactive surface meant to retain
+focus of its own. `denied` gets its own warning-toned glyph and color (a policy rejection, not a
+runtime failure) distinct from `error`'s danger tone, matching `<lyra-tool-result-dialog>`'s
+identical status vocabulary so a call reads the same way in both places. Duration formatting is
+sub-1000ms `"820ms"`, else trimmed to at most one decimal of seconds (`"1.5s"`, `"2s"`).
+
+**Known gotchas:**
+- the default slot is checked for emptiness by scanning `Array.from(this.children)` for elements
+  once on first update, then kept in sync via `slotchange` — only *element* children count (a bare
+  text node assigned to the default slot won't trigger the tooltip)
+- `aria-label` on the host element (if you set one) wins over the component's own generated
+  accessible label (`"name — summary — Status — duration"`); otherwise that generated string is
+  what's announced
+- Escape only dismisses the tooltip when it's open; it does not fire any event or otherwise affect
+  `status`/`open` state, since the chip has no "open" state of its own beyond the tooltip
+
+---
+
+## `lyra-tool-result-view`
+
+Renders a tool call's result via whichever custom renderer a host app has registered for it,
+falling back to `<lyra-json-viewer>` whenever no renderer matches, a renderer's optional `load()`
+rejects, or its `render()` throws. First-party invention (no Web Awesome equivalent). This component
+owns none of the actual visual weight of a populated tool result — that's entirely whatever the
+registered renderer returns; `<lyra-tool-result-view>` is just the dispatch + fallback + loading-state
+shell around it.
+
+**Properties:**
+- `registry?: ToolRendererRegistry` (property only, no attribute) — a custom `Map<string,
+  ToolRendererDefinition>` to dispatch against instead of the module-level default registry (see
+  `registry.ts` below)
+- `toolName: string = ''` (attribute `tool-name`) — the tool's name; the primary dispatch key
+- `result: unknown` (property only, no attribute) — the tool call's result payload, handed to the
+  matched renderer's `render()` (and to `matches()` for shape-based dispatch, and to the
+  `<lyra-json-viewer>` fallback)
+- `args: unknown` (property only, no attribute) — the tool call's original arguments, if available,
+  handed to the matched renderer's `render()` alongside `result`
+- `fallback: string = 'json'` (reflected) — forward-compatible fallback-kind selector; only `"json"`
+  (an unconditional `<lyra-json-viewer>`) is implemented today, but the property/attribute is still
+  accepted so markup that already sets `fallback="…"` for a future value doesn't need to change again
+  once more fallback kinds land
+
+**Events:** `lyra-render-error` (`detail: { toolName: string; error: unknown }`) — fired immediately
+before falling back to `<lyra-json-viewer>`, whether because no renderer matched, a renderer's
+`load()` rejected, or its `render()` threw.
+
+**Slots:** none.
+
+**CSS parts:** `base` — the root wrapper around the resolved renderer's output (or the loading/
+fallback view).
+
+**Themeable custom properties:** none — the component's own styling is deliberately minimal (just
+enough to not collapse to a zero-height inline box); all visible styling comes from whatever
+renderer/`<lyra-skeleton>`/`<lyra-json-viewer>` child is currently mounted.
+
+**Optional peer deps:** none required by the component itself — individual registered renderers may
+of course pull in whatever they need (a charting library, a markdown renderer), which is exactly what
+the lazy `load()` path in the registry exists for.
+
+```html
+<lyra-tool-result-view
+  tool-name="get_weather"
+  .result=${{ tempC: 21, condition: 'cloudy' }}
+  .args=${{ city: 'Brussels' }}
+  @lyra-render-error=${(e) => console.warn('renderer failed', e.detail)}
+></lyra-tool-result-view>
+```
+
+### `registerToolRenderer()` and the tool-renderer registry (`registry.ts`)
+
+A type-keyed dispatch registry — a tiny plugin system so a host app can teach
+`<lyra-tool-result-view>` how to draw the result of e.g. a `get_weather` or `run_query` tool call
+without this library knowing anything about either. Every registered instance dispatches against
+this same module-level registry unless a given `<lyra-tool-result-view>`'s `registry` property is
+set to a different `Map` instance.
+
+**`ToolRendererDefinition`** — the shape of one registered renderer:
+- `render?: (result: unknown, args: unknown) => unknown` — renders the result (and the args that
+  produced it) as UI. Typed as `unknown` rather than Lit's `TemplateResult` so any lit-html-renderable
+  value works (a plain string, a DOM node, an array of templates) — consumers already own their own
+  Lit import and don't need this module to add one
+- `matches?: (payload: unknown) => boolean` — facade/shape-based dispatch predicate, consulted only
+  when no exact `toolName` key matches (see dispatch order below); only ever consulted *before*
+  `load` resolves when supplied inline at registration time — a definition that needs shape-based
+  dispatch and also wants to lazy-load its `render` should register a lightweight synchronous
+  `matches` up front alongside `load`
+- `load?: () => Promise<ToolRendererDefinition | { default: ToolRendererDefinition }>` — lazy loader
+  for a code-split renderer, so a host app can defer the cost of a rarely-used or heavy renderer
+  (e.g. one pulling in a charting library) instead of paying for it on every page that merely
+  registers it. Resolves to either a definition directly, or a `{ default }`-shaped module namespace
+  object, so `load: () => import('./my-renderer.js')` works unmodified when that module's default
+  export is itself a `ToolRendererDefinition`
+
+**Exports:**
+- `registerToolRenderer(name: string, def: ToolRendererDefinition): void` — registers (or
+  overwrites) the renderer for `name` in the module-level default registry
+- `getDefaultToolRendererRegistry(): ToolRendererRegistry` — returns the default `Map` that
+  `registerToolRenderer()` writes to and every `<lyra-tool-result-view>` reads from unless its own
+  `registry` prop is set
+- `findToolRenderer(toolName: string, payload: unknown, registry?: ToolRendererRegistry):
+  ToolRendererDefinition | undefined` — the dispatch function `<lyra-tool-result-view>` calls
+  internally on every resolve; exposed for direct use/testing too
+- `loadToolRenderer(def: ToolRendererDefinition): Promise<ToolRendererDefinition>` — resolves `def`
+  to a definition guaranteed to carry a real `render`, awaiting/unwrapping `def.load()` when present
+  (or returning `def` unchanged otherwise)
+- `clearToolRenderers(): void` — test-only utility that empties the default registry and its
+  `load()` cache, so one test's `registerToolRenderer()` calls can't leak into the next
+
+**Dispatch order** (`findToolRenderer`), exactly as `<lyra-tool-result-view>`'s own `resolve()` uses
+it:
+1. An exact `toolName` key match in the registry.
+2. Failing that, the first entry — in registration order, since a `Map` already iterates that way —
+   whose `matches(payload)` returns `true`. Useful when several tool names share one result shape
+   (e.g. every `*_search` tool returning `{ results: [...] }`) or when the caller doesn't reliably
+   know the tool name at all.
+3. `undefined` if neither matches — `<lyra-tool-result-view>` falls back to `<lyra-json-viewer>` and
+   fires `lyra-render-error`.
+
+Once a definition is found, if it carries `load`, `<lyra-tool-result-view>` shows a
+`<lyra-skeleton variant="rect" height="4rem">` while `loadToolRenderer()` resolves it. The resolved
+`load()` promise is cached keyed by *definition object identity* (a `WeakMap`, not by tool-name
+string) — two different registries that happen to reuse the same tool-name string get independently
+cached loads, and any given lazy definition's `load()` runs at most once no matter how many times
+it's dispatched to, across every `<lyra-tool-result-view>` instance that resolves to it. A **rejected**
+`load()` is *not* cached — the definition stays registered, so a later resolution attempt (e.g. after
+a transient network failure) gets a fresh `load()` call rather than being stuck replaying one failed
+promise forever.
+
+```ts
+import { registerToolRenderer } from '@aceshooting/lyra-ui/tool-result-view/registry.js';
+
+registerToolRenderer('get_weather', {
+  render: (result, args) => html`<weather-card .data=${result} .city=${args?.city}></weather-card>`,
+});
+
+// Lazily loaded, shape-based fallback for every *_search tool:
+registerToolRenderer('web_search', {
+  matches: (payload) => typeof payload === 'object' && payload !== null && 'results' in payload,
+  load: () => import('./search-result-renderer.js'), // default export is a ToolRendererDefinition
+});
+```
+
+**Known gotchas:**
+- `<lyra-tool-result-view>` re-resolves (re-runs the full dispatch → load → render pipeline)
+  whenever `toolName`, `result`, `args`, or `registry` changes, or on first update — a stale
+  in-flight `load()` superseded by a newer change is detected via an internal generation counter and
+  its result is discarded rather than clobbering a more recent render
+- registering under the same `name` twice silently overwrites the earlier definition — there is no
+  warning or error
+- `matches` is a linear scan over every registered definition's `matches` in registration order; it
+  only runs when the exact-name lookup misses, so tool names with a direct registration never pay
+  that scan cost
+- the `fallback` property currently only accepts the effective value `"json"` — setting it to
+  anything else does not change fallback behavior, it's forward-compatible plumbing only
+
+---
+
+## `lyra-tool-result-dialog`
+
+A full tool-call detail overlay: a status/duration header plus a `body` slot where a consumer
+typically places a `<lyra-tabs>` with Input/Preview/JSON/Raw panels. First-party invention (no Web
+Awesome equivalent). This component knows nothing about what's inside that slot — it only supplies
+the modal chrome around it. It is its own standalone overlay implementation (`role="dialog"`,
+focus-trapped, Escape/backdrop-dismissible, scroll-locking) rather than nesting a `<lyra-dialog>` in
+its shadow template, so that slot-forwarding doesn't put a forwarding `<slot>` where a slotted
+`<lyra-tabs>`'s own light-DOM child scan expects real projected content.
+
+**Properties:**
+- `open: boolean = false` (reflected) — whether the dialog is open; set this (or call `close()`) —
+  there is no separate `show()`/`hide()` pair
+- `toolName: string = ''` (attribute `tool-name`) — the tool's name, rendered prominently in the
+  header
+- `status: 'pending'|'running'|'success'|'error'|'denied' = 'pending'` (reflected) — drives the
+  header's status badge; same status vocabulary as `<lyra-tool-call-chip>`
+- `durationMs?: number` (attribute `duration-ms`) — how long the call took, in milliseconds; omitted
+  from the header entirely when unset
+- `maximized: boolean = false` (reflected) — near-fullscreen presentation of the same open dialog
+
+**Methods:** `close(reason: ToolResultDialogCloseReason = 'api'): void` — closes the dialog (no-op if
+already closed), emits `lyra-dialog-close` with `reason`, and returns focus to whatever had it before
+the dialog opened. Built-in triggers call this with `'escape'`/`'backdrop'`/`'close-button'`; a
+consumer's own close affordance (e.g. a footer action button) should call it directly with its own
+reason string so every dismissal path funnels through the same event.
+
+**Events:** `lyra-dialog-close` (`detail: ToolResultDialogCloseReason` — `'escape'|'backdrop'|
+'close-button'|'api'|string`) fired exactly once per dismissal; `lyra-maximize-change` (`detail:
+boolean`, the new `maximized` state) fired when the header's maximize/restore toggle is clicked.
+
+**Slots:** `body` (the dialog's main content — typically a `<lyra-tabs>` with Input/Preview/JSON/Raw
+panels, entirely consumer-assembled), `footer` (optional action buttons, rendered in a bottom row —
+the footer row itself is hidden via `[hidden]` when nothing is slotted)
+
+**CSS parts:** `backdrop`, `panel` (`role="dialog"` while open), `header`, `title` (wrapper around
+tool name/status/duration), `tool-name`, `status`, `duration`, `header-actions`, `maximize-button`,
+`close-button`, `body`, `footer`
+
+**Themeable custom properties:** `--lyra-tool-result-dialog-overlay-color` (default `rgb(0 0 0 /
+0.5)` — the backdrop scrim color; component-specific since no shared overlay token exists),
+`--lyra-tool-result-dialog-maximized-inset` (default `var(--lyra-space-l)` — inset applied to the
+panel while `[maximized]`, overridable e.g. to leave a persistent app rail visible), plus shared
+tokens `--lyra-color-surface/-border/-text-quiet/-brand/-brand-quiet/-success/-success-quiet/
+-danger/-danger-quiet/-warning/-warning-quiet`, `--lyra-space-*`, `--lyra-radius`, `--lyra-shadow`,
+`--lyra-icon-button-size`, `--lyra-focus-ring-*`, `--lyra-transition-base`.
+
+**Optional peer deps:** none.
+
+```html
+<lyra-tool-result-dialog
+  tool-name="run_query"
+  status="success"
+  duration-ms="1240"
+  ?open=${dialogOpen}
+  @lyra-dialog-close=${(e) => (dialogOpen = false)}
+  @lyra-maximize-change=${(e) => console.log('maximized:', e.detail)}
+>
+  <lyra-tabs slot="body">
+    <lyra-tab-panel label="Preview">…</lyra-tab-panel>
+    <lyra-tab-panel label="JSON"><lyra-json-viewer .data=${result}></lyra-json-viewer></lyra-tab-panel>
+  </lyra-tabs>
+  <button slot="footer">Rerun</button>
+</lyra-tool-result-dialog>
+```
+
+While open, `[part="panel"]` takes `role="dialog"` + `aria-modal="true"` with `aria-labelledby`
+pointing at the tool-name element, document scroll is locked, and Tab/Shift+Tab are bounded to the
+panel's own focusable content in header-buttons → `body` slot → `footer` slot order (resolved
+shadow-piercingly, so a slotted custom element's real focusable target inside its own shadow root is
+found too). On open, focus moves to the first focusable element (falling back to the panel itself);
+on close, focus returns to whatever element triggered the open (captured at open time via the active
+element, since the trigger typically lives entirely outside this component). `maximized` toggles
+between the constrained modal size and a near-fullscreen size within the same open dialog and
+open/close lifecycle — unlike `<lyra-widget>`'s fullscreen mode there's no separate non-modal resting
+state, so no additional scroll-lock/focus-trap bookkeeping is needed for that transition alone.
+
+**Known gotchas:**
+- a reconnect that preserves the same element instance (e.g. a drag-and-drop reparent) restores the
+  scroll lock and the document `keydown` listener if `open` was still `true` across the move —
+  `disconnectedCallback`/`connectedCallback` fire back-to-back with no intervening update, so
+  `willUpdate` never reruns to notice `open` didn't change
+- this component deliberately does **not** compose `<lyra-dialog>` internally, even though the two
+  share nearly identical overlay mechanics (focus trap, scroll lock, Escape/backdrop dismiss) — the
+  duplication is intentional so a slotted `<lyra-tabs>` (or any other light-DOM-scanning child) sees
+  real projected content rather than a forwarding `<slot>` from a nested dialog
+- `close()` is a no-op when `open` is already `false` — calling it twice in a row only fires
+  `lyra-dialog-close` once
+- the `maximize`/`close` buttons are always the first elements in the Tab order while open,
+  regardless of visual position, followed by `body` then `footer` content
+
+---
+
+## `lyra-chat-composer`
+
+The message input for a chat/agent conversation surface: an auto-resizing `<textarea>` plus a
+built-in send/stop button. **Form-associated** via the shared `FormAssociated` mixin (same shape as
+`<lyra-date-input>`) — `name: string = ''`, `value: string = ''`, `disabled: boolean = false`
+(reflected), `required: boolean = false` (reflected) are all inherited, along with
+`checkValidity()`/`reportValidity()`, so it participates in native `<form>` submission/validation/
+reset like any other text control.
+
+**Properties (own):**
+- `placeholder: string = ''`
+- `minRows: number = 1` (attribute `min-rows`) — floored to `1` at render time
+- `maxRows: number = 8` (attribute `max-rows`) — floored to at least `minRows`
+- `status: ChatComposerStatus = 'idle'` (reflected) — `'idle' | 'sending' | 'streaming'`; drives the
+  built-in button's icon/label (send vs. stop) and whether Enter still submits
+- `submitOnEnter: boolean = true` (reflected, attribute `submit-on-enter`) — when `false`, Enter
+  always inserts a newline instead of submitting
+
+**Methods (own):** none beyond the inherited `checkValidity()`/`reportValidity()`.
+
+**Events:**
+- `lyra-input` (`detail: { value }`) — fired on every user-driven edit of the textarea, not a
+  programmatic `.value` assignment
+- `lyra-submit` (`detail: { value }`) — fired by Enter (per `submit-on-enter`) or the built-in
+  button while `status="idle"`. `detail.value` is always the exact, untrimmed current value;
+  trimming is left to the consumer. Submitting does **not** clear `value`
+- `lyra-stop` (no detail) — fired by the built-in button while `status` is `"sending"` or
+  `"streaming"`
+
+**Slots:** `leading` (content before the textarea, e.g. an attach-file trigger button), `chips` (an
+attachment tray rendered above the input row), `trailing` (overrides the built-in send/stop button
+entirely when it has assigned content)
+
+**CSS parts:** `base`, `chips`, `row`, `leading`, `textarea`, `trailing`, `action-button`
+
+**Themeable custom properties:** no component-specific custom properties; consumes shared tokens
+`--lyra-space-xs`, `--lyra-space-s`, `--lyra-color-border`, `--lyra-color-surface`,
+`--lyra-color-brand`, `--lyra-color-on-brand`, `--lyra-color-text-quiet`, `--lyra-radius`,
+`--lyra-icon-button-size`, `--lyra-transition-fast`, `--lyra-opacity-disabled`,
+`--lyra-focus-ring-width`, `--lyra-focus-ring-color`, `--lyra-focus-ring-offset`.
+
+**Optional peer deps:** none.
+
+```html
+<lyra-chat-composer
+  id="composer"
+  name="message"
+  placeholder="Message the assistant…"
+  min-rows="1"
+  max-rows="8"
+></lyra-chat-composer>
+<script type="module">
+  const composer = document.getElementById('composer');
+  composer.addEventListener('lyra-submit', (e) => {
+    sendMessage(e.detail.value);
+    composer.value = ''; // the composer never clears itself
+    composer.status = 'sending';
+  });
+  composer.addEventListener('lyra-stop', () => stopGeneration());
+</script>
+```
+
+Auto-resize (`resizeTextarea()`) reads the textarea's own *computed* line-height/padding/border at
+call time rather than assuming a fixed px-per-row constant, so it stays correct under a consumer's
+own font-size/line-height overrides; it grows between `min-rows` and `max-rows`, then switches to
+internal scrolling (`overflow-y: auto`) past `max-rows`. Enter-to-send only fires while
+`submit-on-enter` is `true` (the default): plain Enter submits and prevents the default newline;
+Shift+Enter always inserts a newline regardless of `submit-on-enter`; an IME composition step
+(checked via `isComposing`, with `keyCode === 229` as a defense-in-depth fallback for browsers that
+report `isComposing` inconsistently) is never treated as a submit trigger; and while `status` isn't
+`"idle"`, Enter is left alone to insert a newline instead of resubmitting — the textarea itself is
+**not** auto-disabled during `sending`/`streaming`, so a user can keep composing their next message
+while a previous one is in flight.
+
+**Known gotchas:**
+- `lyra-submit` never clears `value` — the consumer must clear it once a submission is actually
+  accepted, so a failed send can leave the text in place for retry.
+- While `status !== 'idle'`, only the built-in button's behavior changes (it emits `lyra-stop`
+  instead of `lyra-submit`); the textarea keeps accepting input and Enter keeps inserting newlines
+  rather than being blocked.
+- Auto-resize requires a concrete, unitless `line-height` on the textarea (the component sets
+  `line-height: 1.5` in its own styles) — the UA default of `normal` has no single resolved px
+  figure to measure rows against, so overriding `line-height` to a keyword breaks row sizing.
+- The `trailing` slot fully replaces the built-in action button rather than rendering alongside it —
+  once it has assigned content, the library's send/stop icon, its `aria-label`, and its
+  `status`-driven busy styling all disappear, so a custom trailing control needs its own send/stop
+  handling.
+- `[part="chips"]`/`[part="leading"]` are hidden via a JS-tracked `[hidden]` attribute rather than a
+  CSS `:empty` selector, because each always contains a literal `<slot>` child regardless of
+  assigned content.
+
+---
+
+## `lyra-attachment-chip`
+
+A compact chip representing one file queued for (or already part of) a chat message — used in a
+composer's pre-send attachment tray or a sent message's attachments display. Two independent ways
+to populate it: set `file` to a real `File` (fresh from a picker/drop), from which `name`/`size`/
+`mime-type` and the image thumbnail are all auto-derived; or set the plain `name`/`size`/
+`mime-type`/`thumbnail-src` props instead, for reconstructing a chip from server-persisted
+attachment metadata after a page reload, when no real `File` object exists any more. `file` always
+wins when both are present.
+
+**Properties:**
+- `file?: File` (attribute `false`, i.e. property-only) — when set, `name`/`size`/`mimeType`/the
+  image thumbnail are all derived from it, taking precedence over the independent props below
+- `name: string = ''` — filename, used only while `file` is unset
+- `size: number = 0` — file size in bytes, used only while `file` is unset
+- `mimeType: string = ''` (attribute `mime-type`) — used only while `file` is unset
+- `thumbnailSrc: string = ''` (attribute `thumbnail-src`) — thumbnail image URL, used only while
+  `file` is unset; rendered whenever present regardless of `mimeType` (no `file`-derived equivalent
+  exists for a non-image file)
+- `status: AttachmentChipStatus = 'pending'` (reflected) — `'pending' | 'uploading' | 'error' |
+  'done'`; drives the accent tint and which of `progress`/`spinner`/`retry-button` renders
+- `progress: number = 0` — upload completion, 0-100; only meaningful while `status="uploading"`, a
+  value of `0` or `NaN` falls back to the indeterminate spinner
+- `removable: boolean = true` (reflected) — shows the remove (×) button
+
+The component identifies *which* attachment a `lyra-remove`/`lyra-retry` event is about via the
+platform's own `id` attribute/property rather than a second, differently-named prop. Set `id="..."`
+when you have a stable server-side attachment id; when unset and `file` is set, a stable id is
+derived from `` `${file.name}:${file.size}:${file.lastModified}` ``; when neither is available, a
+generated internal id is used as a last resort.
+
+**Events:** `lyra-remove` (`detail: { id }`, only rendered while `removable`), `lyra-retry`
+(`detail: { id }`, only rendered while `status="error"`)
+
+**Slots:** none.
+
+**CSS parts:** `base`, `thumbnail`, `meta`, `name`, `size`, `status-text`, `progress`,
+`progress-fill`, `spinner`, `retry-button`, `remove-button`
+
+**Themeable custom properties:** `--lyra-attachment-chip-accent` (default
+`var(--lyra-color-text-quiet)`), `--lyra-attachment-chip-bg` (default `var(--lyra-color-surface)`),
+`--lyra-attachment-chip-border` (default `var(--lyra-color-border)`) — this trio is swapped per
+`status` (`uploading` → brand/brand-quiet/transparent, `error` → danger/danger-quiet/transparent,
+`done` → success/success-quiet/transparent); plus shared tokens `--lyra-space-xs`, `--lyra-space-s`,
+`--lyra-radius`, `--lyra-color-text`, `--lyra-color-danger`, `--lyra-icon-button-size`,
+`--lyra-transition-fast`, `--lyra-transition-base`, `--lyra-focus-ring-width`,
+`--lyra-focus-ring-color`, `--lyra-focus-ring-offset`.
+
+**Optional peer deps:** none.
+
+Also exported from the package root: `formatFileSize(bytes: number): string` — `512` → `"512 B"`
+(whole bytes never get a decimal), `2415919` → `"2.3 MB"` (every unit past bytes gets exactly one
+decimal place), and a negative or non-finite input (`NaN`, `Infinity`) returns `""` so an unknown
+size renders nothing instead of `"NaN B"`.
+
+```html
+<lyra-attachment-chip name="report.pdf" size="245000" mime-type="application/pdf" status="done"></lyra-attachment-chip>
+<lyra-attachment-chip id="att-2" status="uploading" progress="42"></lyra-attachment-chip>
+<script type="module">
+  import { formatFileSize } from '@aceshooting/lyra-ui';
+
+  const chip = document.createElement('lyra-attachment-chip');
+  chip.file = pickedFile; // name/size/mime-type/thumbnail all derived from the File
+  chip.addEventListener('lyra-remove', (e) => removeAttachment(e.detail.id));
+  chip.addEventListener('lyra-retry', (e) => retryUpload(e.detail.id));
+  console.log(formatFileSize(pickedFile.size));
+</script>
+```
+
+The image thumbnail for a real `File` is a lazily-created `URL.createObjectURL()` blob URL —
+created only from `render()`, i.e. only once a thumbnail is actually about to paint, never eagerly
+on `file` assignment — and revoked automatically once `file` changes to a different `File` (or to
+`undefined`) and on disconnect, so reassigning `file` several times before the next paint never
+leaks URLs that were created but never shown.
+
+**Known gotchas:**
+- `file` always wins over `name`/`size`/`mimeType` when both are set — assigning those props while
+  `file` is also set has no visible effect on the rendered chip.
+- A `0`-byte size and an unset size are indistinguishable (there's no separate flag for "genuinely
+  empty file"); the `size` part is hidden entirely rather than showing a literal `"0 B"`.
+- `progress` only renders as a numeric bar when `status="uploading"` **and** `progress` is finite
+  and `> 0`; otherwise it's either nothing (non-`uploading` status) or the indeterminate spinner
+  (`uploading` with no known progress).
+- `thumbnailSrc` is used whenever present regardless of `mimeType` — pass a URL that's already known
+  to be an image; there's no non-image fallback check for it the way there is for `file`.
+
+---
+
+## `lyra-stream-status`
+
+A compact status indicator for a single streaming connection (SSE, WebSocket, long-poll, …), with
+built-in heartbeat-aware stall detection. First-party invention (no Web Awesome equivalent). The
+host drives `phase` directly for `idle`/`connecting`/`streaming`, and calls the imperative
+`recordActivity()` method on every *semantic* frame received while streaming — a real content
+chunk, never a transport-level keep-alive ping. This component has no payload-inspection logic of
+its own: "ignore heartbeats" is entirely call-site discipline, which is exactly why a connection
+that's only sending keep-alives (no real content) for longer than `stall-threshold-ms` correctly
+reads as stalled.
+
+**Properties:**
+- `phase: 'idle' | 'connecting' | 'streaming' | 'stalled' = 'idle'` (reflected) — current
+  connection phase. Fully public and directly settable by the host at any time, including a manual
+  override to `'stalled'`; the component never fights a host-driven reassignment.
+- `stallThresholdMs: number = 10000` (attribute `stall-threshold-ms`) — how long `phase` may stay
+  `'streaming'` with no `recordActivity()` call before the component auto-transitions to
+  `'stalled'`. A non-finite or `<= 0` value disables the stall timer entirely (arming becomes a
+  no-op, so the phase will never auto-stall).
+
+**Methods:**
+- `recordActivity(): void` — call on every semantic (non-heartbeat) frame received while
+  streaming.
+  - While `phase === 'streaming'`: (re)arms the stall timer, pushing the stall deadline
+    `stallThresholdMs` further out.
+  - While `phase === 'stalled'`: recovers — `phase` becomes `'streaming'` again (firing
+    `lyra-recover` and arming the timer fresh, via the same transition handling a direct host
+    assignment would also go through).
+  - While `phase` is `'idle'` or `'connecting'`: a no-op. Safe to call defensively before formally
+    flipping to `'streaming'`; it never throws or starts a timer early.
+
+**Events:** `lyra-stall` (no detail payload) — fires whenever `phase` transitions into `'stalled'`
+from any other phase, whether timer-driven or via a direct host assignment. `lyra-recover` (no
+detail payload) — fires whenever `phase` transitions out of `'stalled'` to any other phase,
+whether via `recordActivity()` or a direct host assignment. Neither fires for a same-value
+reassignment, and neither fires for whatever phase the element happens to *mount* with — only a
+later change counts as a transition.
+
+**Slots:** default (custom copy shown only while `phase="stalled"`, e.g. "Taking longer than
+usual…" — falls back to a built-in default message when nothing is slotted), `actions` (a
+stop/retry button row; always present in the template regardless of `phase` — its wrapper's
+visibility is driven purely by whether anything is slotted into it, not by `phase`)
+
+**CSS parts:** `base`, `indicator`, `message`, `actions`
+
+**Themeable custom properties:** shared tokens only — `--lyra-color-text-quiet` (idle dot color),
+`--lyra-color-brand` (connecting/streaming dot color), `--lyra-color-warning` (stalled dot color,
+message text color, stalled border), `--lyra-color-warning-quiet` (stalled background tint),
+`--lyra-space-s` / `--lyra-space-xs` (base gap, stalled padding, actions gap), `--lyra-radius`
+(base corner radius), `--lyra-transition-base` (background/border-color transitions and the
+streaming pulse animation's cycle length). The component also sets two internal, phase-driven
+custom properties (`--lyra-stream-status-dot-color`, `--lyra-stream-status-dot-opacity`) on
+`:host`, but its own `:host([phase="..."])` rules outrank a page-level override for every phase
+except the default `idle`, so these aren't a practical external theming hook.
+
+**Optional peer deps:** none.
+
+```html
+<lyra-stream-status phase="streaming" stall-threshold-ms="8000">
+  <span slot="actions"><button>Stop</button></span>
+</lyra-stream-status>
+```
+```ts
+const status = document.querySelector('lyra-stream-status')!;
+status.addEventListener('lyra-stall', () => console.warn('stream stalled'));
+status.addEventListener('lyra-recover', () => console.info('stream recovered'));
+
+// on every real content chunk from the transport (never on a keep-alive ping):
+status.recordActivity();
+```
+
+Internally, the inactivity timer runs only while `phase === 'streaming'`. It's (re)armed whenever
+the phase transitions to `'streaming'` (directly, or via `recordActivity()` recovering from
+`'stalled'`) and on every subsequent `recordActivity()` call while already streaming; it's disarmed
+the instant `phase` becomes anything else, including a host-driven reassignment away from
+`'streaming'` — so a stale timer can never fire a stall transition after the host has already moved
+on. Phase transitions into/out of `'stalled'` are announced through an internal
+`<lyra-live-region>` rather than a hand-rolled `aria-live` region: entering `'stalled'` announces
+"Connection stalled." with `mode="assertive"` (a stall can need the user's attention before they
+give up and navigate away); recovering announces "Connection restored." with `mode="polite"` (good
+news doesn't need to interrupt). Calling `recordActivity()` itself never announces anything, no
+matter how often the host calls it — only the phase *transition* announces, exactly once. The
+decorative indicator dot is `aria-hidden` (a color/motion cue only) and only pulses while
+`phase="streaming"`; `'stalled'` is styled as a warning tone, not danger, since a stall is usually
+recoverable — a host that wants to escalate after N stalls can scope its own CSS off
+`[phase="stalled"]`, or stop rendering this component and show its own danger-styled error state
+instead. The pulse animation is suppressed under `prefers-reduced-motion: reduce`.
+
+**Known gotchas:**
+- `recordActivity()` is a plain instance method, not a reactive property — there's nothing to bind
+  to in a template; call it directly from streaming/application code on every real chunk received.
+- Never call `recordActivity()` for a heartbeat/keep-alive ping. This component has no
+  payload-inspection logic of its own, so a connection that's only sending pings (no real content)
+  for longer than `stall-threshold-ms` is *supposed* to read as stalled — that's the entire
+  point of the API.
+- Setting `stallThresholdMs` to `0`, a negative number, or a non-finite value disables the stall
+  timer outright; the component will stay `'streaming'` forever until the host manually changes
+  `phase`.
+- `phase` remains directly settable at all times; assigning `'stalled'` yourself fires `lyra-stall`
+  and the assertive announcement exactly as if the timer had fired.
+- The `actions` slot's wrapper is always present in the DOM and toggled with the `hidden` attribute
+  based on slotted content, not gated by `phase` — content placed there is visible regardless of
+  the current phase.
+
+---
+</markdown>
+
+---
+
+## `lyra-virtual-list`
+
+A generic windowed/virtualized list host. Renders only the items within the current viewport (plus
+`overscan` padding rows on each side) as real DOM, regardless of how large `items` is, so a
+multi-thousand-row chat-history sidebar (or a long message thread) stays cheap to scroll. Content is
+entirely caller-supplied: `renderItem(item, index)` returns whatever `lit-html` value should represent
+that row, and `keyFunction(item, index)` gives it a stable identity for DOM reconciliation. First-party
+invention (no Web Awesome equivalent).
+
+**Properties:**
+- `items: unknown[] = []` (attribute: false) — the full, non-windowed item collection. JS-only; set via
+  a property/lit-html binding (`.items=`), not an HTML attribute.
+- `renderItem: (item: unknown, index: number) => unknown = () => nothing` (attribute: false) — renders
+  one row's content, typically returning a `lit-html` `TemplateResult`. JS-only.
+- `keyFunction?: (item: unknown, index: number) => string | number` (attribute: false) — derives a
+  row's stable reconciliation key. JS-only. Falls back to the item's index in `items` when omitted,
+  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) — reserved for a future sticky-header sectioning
+  feature; accepted but **not currently read or rendered** — every row still renders flat, in `items`
+  order.
+- `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.
+- `overscan: number = 6` — extra rows rendered beyond the visible viewport on each side.
+- `activeId: string = ''` (attribute `active-id`) — when set and it matches a row's `keyFunction`
+  result (compared as a string), that row is smoothly scrolled into view whenever this changes, and
+  rendered with `aria-current="true"`.
+- `loading: boolean = false` (reflected) — sets `aria-busy` on the scroll container and a `cursor:
+  progress` style; does not by itself gate `lyra-load-more` (see below).
+- `hasMore: boolean = false` (attribute `has-more`, reflected) — when true, scrolling near the bottom
+  fires `lyra-load-more` (gated by `loading`).
+
+**Exported types:** `VirtualListRange { start: number; end: number }` (the `lyra-visible-range-changed`
+detail shape); `VirtualListGroup { key: string | number; label?: string; startIndex: number }` — a
+placeholder shape for the not-yet-implemented grouping feature above. No exported helper functions ship
+in this pass (a paired `groupByRecency()` helper referenced in the source's own class doc doesn't exist
+yet).
+
+**Events:** `lyra-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), `lyra-visible-range-changed` (`detail: VirtualListRange`, the
+current visible, non-overscanned item index range — fired only when it actually changes)
+
+**Slots:** none — all content comes from `renderItem`.
+
+**CSS parts:** `base` (the scrollable container, `role="list"`, `tabindex="0"`), `spacer` (the
+full-content-height inner element establishing true scroll extent), `row` (one rendered row's
+absolutely-positioned wrapper, `role="listitem"`)
+
+**Themeable custom properties:** `--lyra-virtual-list-height` (default `24rem` — the host's bounded
+scroll extent; component-specific since a virtualized list is meaningless without a sized viewport),
+plus shared `--lyra-focus-ring-width/-color/-offset` (inward-offset ring on `[part="base"]`, negative
+so it isn't clipped by the container's own `overflow: auto`).
+
+**Optional peer deps:** none.
+
+```html
+<lyra-virtual-list
+  .items=${sessions}
+  .renderItem=${(item, index) => html`
+    <lyra-conversation-item
+      id=${item.id}
+      title=${item.title}
+      .timestamp=${item.updatedAt}
+      ?active=${item.id === currentId}
+    ></lyra-conversation-item>
+  `}
+  .keyFunction=${(item) => item.id}
+  active-id=${currentId}
+  ?has-more=${hasMorePages}
+  ?loading=${isLoadingMore}
+  @lyra-load-more=${() => loadNextPage()}
+  @lyra-visible-range-changed=${(e) => console.log('visible', e.detail.start, e.detail.end)}
+></lyra-virtual-list>
+```
+
+Every row — in both `row-height` modes — is positioned by a `transform: translateY(offset)` computed
+from a single cumulative offsets array rebuilt on every update, rather than by page flow; this is what
+lets a small DOM window exist while the scrollbar still reflects the true total content height. In
+`row-height="auto"` mode, unmeasured rows contribute a fixed estimate to that array until their real
+`ResizeObserver`-reported height lands, so only rows after a newly-measured one shift on each
+measurement rather than the whole list reflowing. The offsets rebuild is an `O(n)` loop appropriate for
+hundreds to a few thousand rows (a scrollable history sidebar); it is not the right approach for a
+hundred-thousand-row list without further work.
+
+**Known gotchas:**
+- `items`, `renderItem`, `keyFunction`, and `groups` are all `attribute: false` — they must be set as
+  JS properties (`.items=`, `.renderItem=`, …), never as HTML attribute strings.
+- The container is `role="list"` with rows `role="listitem"`, deliberately not `listbox`/`option` —
+  this component only provides windowing, not the roving-tabindex/`aria-activedescendant`
+  keyboard-interaction contract a real `listbox` requires. `active-id` only scrolls a row into view and
+  marks it `aria-current`; it is not a selection widget. Compose your own selection behavior on top if
+  needed.
+- `[part="base"]` carries `tabindex="0"` unconditionally, since `renderItem`'s caller-supplied content
+  isn't guaranteed to contain a focusable element and an otherwise-unreachable-by-keyboard scroll
+  region would result.
+- `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.
+
+---
+
+## `lyra-conversation-item`
+
+A selectable row representing one chat session in a history sidebar list. Usable standalone or as the
+`renderItem()` payload of `<lyra-virtual-list>`; has no dependency on that (or any) other component.
+First-party invention (no Web Awesome equivalent).
+
+**Properties:**
+- `title: string = ''` — the session's display title. Falls back to "Untitled conversation" when empty
+  (display only — the property itself is never mutated by that fallback).
+- `excerpt: string = ''` — a short preview snippet of the last message. Omit for no excerpt line.
+- `timestamp?: Date | string` (attribute: false) — accepts a `Date` or anything `new Date()` can parse
+  (e.g. an ISO 8601 string); invalid input is treated as unset (no `<time>` rendered).
+- `formatTimestamp?: (date: Date) => string` (attribute: false) — overrides the default absolute-time
+  rendering (clock time for same-day timestamps, otherwise a calendar date). Not a fuzzy "2 hours ago"
+  relative string — bucketed relative grouping is a list-level concern, not this row's job.
+- `active: boolean = false` (reflected) — whether this is the currently-selected/open session; drives
+  the brand-quiet background treatment.
+- `editable: boolean = true` (reflected) — whether inline-rename is available at all. When `false`, the
+  rename button never renders and the row can never enter its editing state.
+
+**Events:** `lyra-select` (no detail payload — identify the row via the platform `id` attribute on the
+event's `target`/`currentTarget`, the same convention `<lyra-attachment-chip>` uses; fires on a click on
+`[part="option"]` outside the rename button/`actions` slot, or Enter/Space while it's focused, only
+while not currently renaming), `lyra-rename` (`detail: { title: string }` — an in-place rename was
+committed via Enter or blur-while-editing; does not mutate `title` itself, this is a controlled
+component — not fired when the trimmed draft is empty or unchanged from the original `title`, treated
+as an implicit cancel)
+
+**Slots:** `actions` — overflow/icon-button controls rendered at the trailing edge of the row (e.g. a
+future pin/delete button); only visually shown once it actually has assigned elements.
+
+**CSS parts:** `base`, `option`, `content`, `title`, `title-input`, `rename-button`, `excerpt`,
+`timestamp`, `actions`
+
+**Themeable custom properties:** shared tokens only — `--lyra-space-xs/-s/-m`, `--lyra-radius`,
+`--lyra-transition-fast`, `--lyra-color-text/-text-quiet/-brand/-brand-quiet/-surface`,
+`--lyra-focus-ring-width/-color/-offset`, `--lyra-icon-button-size`.
+
+**Optional peer deps:** none.
+
+```html
+<lyra-conversation-item
+  id="sess_123"
+  title="Q3 roadmap planning"
+  excerpt="Let's revisit the timeline for the launch…"
+  .timestamp=${session.updatedAt}
+  ?active=${session.id === currentSessionId}
+  @lyra-select=${(e) => openSession(e.currentTarget.id)}
+  @lyra-rename=${(e) => renameSession(e.currentTarget.id, e.detail.title)}
+>
+  <button slot="actions" aria-label="Delete conversation">✕</button>
+</lyra-conversation-item>
+```
+
+`role="option"` (not `"button"`) lives on `[part="option"]`, since this is meant to sit inside a
+`role="listbox"` history list; used truly standalone it's still fully operable, just missing that ARIA
+parent context. Because `role="option"` forbids focusable descendants, the rename button and the
+`actions` slot are rendered as DOM *siblings* of `[part="option"]` (not nested inside it) — the same
+constraint the in-place rename `<input>` runs into one level deeper, which is why `[part="option"]`
+sheds its `role`/`tabindex`/`aria-selected`/`aria-label` entirely for the duration of an edit rather than
+just visually swapping content.
+
+**Known gotchas:**
+- `lyra-select` carries no detail payload at all — read the session id off the event's own `target`/
+  `currentTarget`, not a `detail` field.
+- Renaming is a controlled interaction: committing `lyra-rename` never updates `title` locally: the
+  consumer must apply the new title once it's actually persisted.
+- An empty or unchanged (post-trim) rename draft is treated as an implicit cancel — no `lyra-rename`
+  fires, and the row silently reverts to showing `title`.
+- Rename is triggered only by the dedicated pencil-icon button, never a double-click on the title —
+  double-click has no keyboard/screen-reader equivalent and would also swallow the row's own
+  single-click `lyra-select`.
+- While renaming, `[part="option"]` has no `role`/`tabindex`/`aria-selected`/`aria-label` at all — a
+  screen reader briefly stops announcing it as a listbox option for the duration of the edit.
+
+---
+
+## `lyra-model-select`
+
+A provider/model picker that renders as a closed dropdown when a fixed `catalog` is available, or as a
+filterable free-text combobox when it isn't (or when `allow-custom` explicitly permits typing something
+outside the catalog). Form-associated (hand-rolled internals via `attachInternals()` directly, not the
+shared `FormAssociated` mixin — same reasoning as `lyra-combobox`/`lyra-select`: see the shared-foundation
+notes). Built on the same trigger-button/`aria-activedescendant` listbox technique `<lyra-select>` uses
+and the filter-as-you-type suggestion-popup technique `<lyra-combobox>` uses, without composing either
+element. First-party invention (no Web Awesome equivalent).
+
+**Exported types:**
+- `LyraModelCatalogEntry { id: string; label: string }` — one catalog row.
+- `LyraModelCatalog = string[] | LyraModelCatalogEntry[]` — either every entry is a plain string (used
+  as both id and label) or every entry is a full `{ id, label }` row; the two shapes are not meant to be
+  mixed within one array.
+
+**Properties:**
+- `provider: string = ''` — informational only (e.g. `'ollama'`); rendered as a small leading badge.
+- `catalog?: LyraModelCatalog` (attribute: false) — the full model list. Omit (or leave empty) to fall
+  back to plain free-text entry.
+- `allowCustom: boolean = false` (attribute `allow-custom`, reflected) — let the user type/commit a
+  value that isn't in `catalog`, even when `catalog` is non-empty.
+- `placeholder: string = ''`
+- `name: string = ''`
+- `disabled: boolean = false` (reflected)
+- `required: boolean = false` (reflected — enforced via `internals.setValidity()`)
+- `open: boolean = false` (reflected)
+- `value: string` — getter/setter (hand-rolled, not the `FormAssociated` mixin); the current model id,
+  `''` when nothing is selected. Writing it calls `internals.setFormValue()` synchronously.
+
+**Mode switching:** `closedMode` (private) is `true` whenever `normalizedCatalog.length > 0 &&
+!allowCustom` — a non-empty `catalog` with `allowCustom` left `false` renders the closed dropdown
+trigger-button UI (`[part="trigger"]`, `role="combobox"` on a `<button>`, no typing). Any other
+combination (`catalog` empty/unset, or `allowCustom` true) renders the free-text `<input>` UI
+(`[part="combobox"]`/`[part="combobox-input"]`) with live substring filtering against the catalog (id or
+label, case-insensitive). The mode is re-evaluated on every render, so toggling `allowCustom` or clearing
+`catalog` at runtime switches modes live, repositioning the shared `[part="listbox"]` popover against
+whichever element is the active anchor.
+
+A `value` that isn't present in `catalog` (e.g. a model id saved from a provider whose live catalog has
+since changed) is never silently dropped: it's appended to the rendered option list as a synthetic,
+visually-distinct row (dashed border, italic label, "not in catalog" badge) computed fresh from
+`catalog` + `value` on every access, without ever mutating the `catalog` property itself.
+
+**Events:** `lyra-change` (`detail: { value: string; inCatalog: boolean }` — fired when a value is
+selected from the listbox or committed in free-text mode; `inCatalog` reflects whether that value was
+actually present in `normalizedCatalog`, so a consumer can flag a freshly-typed custom value distinctly
+from a real catalog pick)
+
+**Slots:** none.
+
+**CSS parts:** `trigger`, `combobox`, `combobox-input`, `provider-badge`, `listbox`, `option`,
+`option-label`, `option-badge`
+
+**Themeable custom properties:** shared tokens only — `--lyra-space-xs/-s`,
+`--lyra-color-border/-surface/-brand/-brand-quiet/-text-quiet`, `--lyra-radius`, `--lyra-shadow`,
+`--lyra-focus-ring-width/-color/-offset`, `--lyra-icon-button-size`, `--lyra-transition-fast`,
+`--lyra-opacity-disabled`.
+
+**Optional peer deps:** none.
+
+```html
+<lyra-model-select
+  provider="openai"
+  .catalog=${[
+    { id: 'gpt-4o', label: 'GPT-4o' },
+    { id: 'gpt-4o-mini', label: 'GPT-4o mini' },
+  ]}
+  value="gpt-4o"
+  placeholder="Choose a model…"
+  @lyra-change=${(e) => setModel(e.detail.value, e.detail.inCatalog)}
+></lyra-model-select>
+
+<!-- No fixed catalog yet: falls back to free-text entry -->
+<lyra-model-select provider="ollama" placeholder="Type a model id…" allow-custom></lyra-model-select>
+```
+
+**Known gotchas:**
+- `catalog` must be homogeneous — an array of plain strings, or an array of `{ id, label }` objects, not
+  a mix; `LyraModelCatalog` is a union of two array *types*, not an array of a union item type.
+- The synthetic "not in catalog" row only ever appears when `catalog` is non-empty and `value` isn't one
+  of its ids — with no `catalog` at all, there's no catalog list to diff `value` against, so no badge.
+- `value`/form-association here is hand-rolled via `attachInternals()` directly, not the shared
+  `FormAssociated` mixin — mirrors `lyra-combobox`/`lyra-select`'s identical divergence.
+- `aria-invalid`/`data-invalid` only reflect once the control has been blurred (touched) at least once,
+  matching `lyra-select`'s identical pattern — validity styling never flashes on first render.
+- In free-text mode, the input's displayed text is `query` only while `open`; while closed it shows the
+  committed value's label — so setting `.value` programmatically doesn't require also touching the live
+  typed text.
+
+---
+
+## `lyra-slider`
+
+A numeric range control (e.g. an LLM "temperature" setting). **Form-associated** via the shared
+`FormAssociated` mixin (`name`, `value`, `disabled`, `required` all inherited). Mirrors native `<input
+type="range">` semantics: `value` is the string form-submitted via the mixin, `valueAsNumber` is the
+ergonomic numeric accessor (matching native `<input type=range>`'s IDL attribute of the same name) kept
+in sync with it in both directions. First-party invention (no Web Awesome equivalent).
+
+**Properties:**
+- `min: number = 0`
+- `max: number = 100`
+- `step: number = 1`
+- `label: string = ''` — accessible name set as `aria-label` on the `role="slider"` thumb; a plain
+  `aria-label` attribute on the host itself is honored as a fallback when this is left unset (matching
+  `<lyra-checkbox>`/`<lyra-switch>`).
+- `showValue: boolean = true` (attribute `show-value`) — whether to render the current numeric value as
+  visible text next to the track. Not reflected; toggle it off via the `.showValue=${false}` property
+  binding — a bare `show-value="false"` content attribute is still truthy, since presence is all Lit's
+  default boolean converter checks.
+- Inherited from `FormAssociated`: `name: string = ''`, `value: string` (form-submitted string form),
+  `disabled: boolean = false` (reflected), `required: boolean = false` (reflected).
+
+**Accessor:** `valueAsNumber: number` — get/set. Reading always returns a finite, clamped, step-snapped
+number, even if `value` is momentarily `""` (e.g. right after `form.reset()`, before the mount-time
+default reseeds it), by falling back to the midpoint of `[min, max]`. Writing clamps/snaps the input and
+stringifies the result back into `value`.
+
+**Events:** `lyra-input` (`detail: { value: number }` — fired continuously during an active drag or a
+keyboard step, including OS key-repeat while a key is held, mirroring native `<input type=range>`'s
+`input` event), `lyra-change` (`detail: { value: number }` — fired once an interaction commits: on
+pointerup for a drag, or on keyup for a keyboard step, so a single Arrow/Home/End/PageUp/PageDown press
+fires both `lyra-input` and `lyra-change`, mirroring native `<input type=range>`'s own `change`-on-every-
+committed-step behavior)
+
+**Slots:** none.
+
+**CSS parts:** `base` (row wrapping the track and optional value readout), `track`, `fill` (filled
+portion from `min` up to the current value), `thumb` (`role="slider"`), `value` (numeric readout, shown
+when `show-value` is true)
+
+**Themeable custom properties:** shared tokens only — `--lyra-space-s`,
+`--lyra-color-border/-brand/-surface/-text-quiet`, `--lyra-shadow`,
+`--lyra-focus-ring-width/-color/-offset`, `--lyra-opacity-disabled`.
+
+**Optional peer deps:** none.
+
+```html
+<lyra-slider
+  name="temperature"
+  min="0"
+  max="2"
+  step="0.1"
+  label="Temperature"
+  .valueAsNumber=${0.7}
+  @lyra-input=${(e) => setDraftTemperature(e.detail.value)}
+  @lyra-change=${(e) => commitTemperature(e.detail.value)}
+></lyra-slider>
+```
+
+An unset `value` is eagerly defaulted — on connect, and again after `form.reset()` — to the midpoint of
+`[min, max]` snapped to `step`, the same "range sanitization algorithm" default a native range input
+applies. A slider therefore always represents *some* number, so `required` only has a narrow window to
+block submission before that default lands, matching how `required` isn't a meaningful constraint on a
+native range input either.
+
+**Known gotchas:**
+- `valueAsNumber` always returns a real, clamped number — never `NaN` or `""` — even reading it in the
+  brief window right after a `form.reset()`.
+- Under `direction: rtl`, physical ArrowRight/ArrowLeft swap which one counts as "forward" (increasing
+  value); ArrowUp/ArrowDown are never swapped, since direction only affects the horizontal inline axis.
+- Changing `min`/`max`/`step` after mount automatically re-clamps/re-snaps the current `value` in the
+  next update — narrowing the domain can silently move the slider's value.
+- A pointer drag fires `lyra-input` continuously and a single `lyra-change` on release; a keyboard step
+  fires exactly one of each per press, but OS key-repeat while a key is held re-fires `lyra-input` on
+  every repeat while still only committing `lyra-change` once, on the eventual keyup.
+
+---
+
+## `lyra-tool-select-dialog`
+
+A category-grouped, filterable, searchable tool-enablement dialog for picking which agent tools are
+available in a conversation. Its own standalone overlay implementation (`role="dialog"`, focus-trapped,
+Escape/backdrop-dismissible, scroll-locking) rather than nesting `<lyra-dialog>` in its shadow template —
+duplicated locally the same way `<lyra-tool-result-dialog>` does, so this component has no dependency on
+the general-purpose dialog. First-party invention (no Web Awesome equivalent).
+
+**Exported types:**
+- `ToolSelectDialogTool { id: string; name: string; description?: string; category?: string; icon?:
+  string; disabled?: boolean; disabledReason?: string }` — one selectable agent tool. `category` groups
+  the row into a heading; tools with no `category` (or an empty/whitespace-only one) fall into a
+  trailing "Other" bucket. `icon` is a literal glyph (e.g. an emoji) rendered next to `name` — an opaque
+  string, not a registry lookup, the same convention `<lyra-tool-call-chip>`'s `icon` uses. `disabled`
+  individually gates a tool regardless of `useDefaults`/`selected` (e.g. a tool requiring admin
+  approval); `disabledReason` is supporting text shown under a disabled row, ignored when `disabled` is
+  falsy.
+- `ToolSelectFilter = (tool: ToolSelectDialogTool, query: string) => boolean` — a predicate deciding
+  whether `tool` matches an already-trimmed, already-lowercased `query`. Assign `filter` to replace the
+  built-in case-insensitive name/description substring match entirely (mirrors `<lyra-combobox>`'s
+  `OptionFilter` convention).
+- `ToolSelectionChangeDetail { selected: string[]; useDefaults: boolean }` — the `lyra-change` detail
+  shape.
+- `ToolSelectDialogCloseReason = 'escape' | 'backdrop' | 'api' | string` — the `lyra-close` detail;
+  `'escape'`/`'backdrop'` come from the dialog's own built-in dismiss triggers, any other string is
+  whatever a caller passes to `close()` directly.
+
+**Properties:**
+- `open: boolean = false` (reflected) — set this (or call `close()`) to dismiss; there is no separate
+  `show()`/`hide()` pair.
+- `tools: ToolSelectDialogTool[] = []` (attribute: false) — the full set of tools a consumer offers,
+  across all categories.
+- `selected: string[] = []` (attribute: false) — the currently-enabled tool ids.
+- `useDefaults: boolean = false` (attribute `use-defaults`, reflected) — whether the conversation is
+  using the default tool set (`true`) or a custom selection (`false`).
+- `label: string = 'Select tools'` — the dialog's visible heading and accessible name.
+- `searchPlaceholder: string = 'Search tools…'` (attribute `search-placeholder`)
+- `filter: ToolSelectFilter | null = null` (attribute: false) — overrides the built-in
+  case-insensitive name/description substring match.
+
+**Methods:** `close(reason: ToolSelectDialogCloseReason = 'api'): void` — closes the dialog, emits
+`lyra-close` with `reason`, and returns focus to whatever had it before the dialog opened.
+
+**Events:** `lyra-change` (`detail: ToolSelectionChangeDetail` — the enabled-tool selection or the
+`useDefaults` toggle changed), `lyra-close` (`detail: ToolSelectDialogCloseReason` — fired exactly once
+per dismissal, via Escape, a backdrop click, or a `close()` call)
+
+**Slots:** `footer` — optional action buttons (e.g. a "Done" button), rendered in a bottom row. Changes
+already apply live via `lyra-change`, so this slot is purely optional; only visually shown once it has
+assigned elements.
+
+**CSS parts:** `backdrop`, `panel`, `header`, `title`, `subtitle`, `search-row`, `search-input`,
+`defaults-row`, `defaults-toggle`, `defaults-hint`, `body`, `empty`, `category`, `category-heading`,
+`category-count`, `category-list`, `tool-row`, `tool-checkbox`, `tool-name`, `tool-icon`,
+`tool-description`, `tool-disabled-reason`, `footer`
+
+**Themeable custom properties:** `--lyra-tool-select-dialog-overlay-color` (default `rgb(0 0 0 / 0.5)` —
+the backdrop scrim color; component-specific since no shared overlay token exists, mirrors
+`<lyra-dialog>`'s/`<lyra-tool-result-dialog>`'s identical pattern), plus shared `--lyra-space-*`,
+`--lyra-color-surface/-border/-text/-text-quiet/-warning`, `--lyra-radius`, `--lyra-shadow`,
+`--lyra-focus-ring-width/-color/-offset`, `--lyra-opacity-disabled`, `--lyra-icon-button-size`.
+
+**Optional peer deps:** none — internally renders `<lyra-checkbox>` and `<lyra-switch>`, both bundled
+dependencies of this package imported directly, not optional peers.
+
+```html
+<lyra-tool-select-dialog
+  label="Select tools"
+  .tools=${[
+    { id: 'search', name: 'Web search', category: 'Research' },
+    { id: 'python', name: 'Python', category: 'Code', description: 'Run sandboxed Python' },
+    { id: 'admin', name: 'Admin console', disabled: true, disabledReason: 'Requires admin approval' },
+  ]}
+  .selected=${enabledToolIds}
+  ?use-defaults=${usingDefaults}
+  ?open=${dialogOpen}
+  @lyra-change=${(e) => updateTools(e.detail.selected, e.detail.useDefaults)}
+  @lyra-close=${() => (dialogOpen = false)}
+>
+  <button slot="footer" @click=${(e) => e.target.closest('lyra-tool-select-dialog').close('done')}>
+    Done
+  </button>
+</lyra-tool-select-dialog>
+```
+
+`useDefaults` is a single top-level switch: while `true`, every per-tool checkbox renders disabled
+(still reflecting whatever `selected` holds — populate that with the actual default tool set whenever
+`useDefaults` is true) alongside a hint explaining that turning the switch off is how to customize.
+Turning it off is the only control that both flips `useDefaults` to `false` *and* unlocks the per-tool
+checkboxes for editing.
+
+**Known gotchas:**
+- No built-in footer/close button — dismissal happens via Escape, a backdrop click, or a consumer's own
+  `footer`-slotted action calling `close()` directly.
+- A row is effectively disabled whenever *either* its own `tool.disabled` is true *or* the top-level
+  `useDefaults` switch is on — a tool without `disabled` set can still render as a locked checkbox while
+  `useDefaults` is true.
+- `disabledReason` text only renders when both `tool.disabled` and `tool.disabledReason` are set.
+- Categories are grouped in first-seen order across `tools`; an empty/whitespace-only `category` folds
+  into a trailing "Other" bucket that's always rendered last. A category left with zero matches after
+  filtering is dropped entirely, not rendered as an empty heading.
+- Reconnecting the element while still `open` (e.g. a drag-and-drop reparent that keeps the same
+  instance) automatically re-acquires the scroll lock and keydown trap it dropped in
+  `disconnectedCallback`.
+- The search input is the first focusable element in the panel and receives focus automatically on open.
+
+---
+
+## `lyra-citation-badge`
+
+An inline `[n]` citation marker with a hover/focus preview popover and confidence/verification-status
+coloring. First-party invention (no Web Awesome equivalent). Meant to sit inline in a chat message's
+text, each badge carrying a `source-id` that matches a corresponding `<lyra-source-card>` shown
+elsewhere on the page (a sibling component in this family) — this component never imports or knows
+anything about `<lyra-source-card>`, it only carries the id through its event details.
+
+**Properties:**
+- `index: number = 1` — the citation number shown, e.g. `3` renders as `[3]`.
+- `status: CitationBadgeStatus = 'default'` (reflected) — one of `'default' | 'high' | 'medium' |
+  'low' | 'verified' | 'unverified'`; drives the badge's color and (unless `label` is set) part of
+  its accessible name.
+- `sourceId: string = ''` (attribute `source-id`) — id of a corresponding `<lyra-source-card>`,
+  echoed back verbatim in both events; never read or validated by this component.
+- `href: string = ''` — optional direct link target for the citation's source, carried into
+  `lyra-citation-open`'s detail as-is; this component never navigates.
+- `label: string = ''` — overrides the computed accessible name (`"Citation {index}[, {status}]"`).
+
+**Events:**
+- `lyra-citation-activate` (`detail: { sourceId: string; index: number }`) — fires on click, or on
+  Enter while focused (native `<button>` behavior, no listener needed for the Enter case). The
+  lightweight "jump to this source" signal.
+- `lyra-citation-open` (`detail: { sourceId: string; index: number; href?: string }`) — fires on
+  dblclick, or on Space while focused. A distinct "full preview" signal; `href` is `undefined` when
+  the `href` prop isn't set. A double-click also fires two `lyra-citation-activate` events (one per
+  constituent click, standard browser `dblclick` behavior) in addition to the one `lyra-citation-open`.
+
+**Slots:** default — rich preview/tooltip content (e.g. a filename + excerpt), shown in a floating
+popover on hover/focus. This is *not* the badge's visible content (the badge always renders
+`[index]`); nothing renders at all (no hover affordance) when this slot is empty.
+
+**CSS parts:** `base` (the clickable `<button>`), `bracket` (each of the two literal `[`/`]` glyphs),
+`index` (the citation number), `popover` (the floating preview panel, only meaningful while open).
+
+**Themeable custom properties:** `--lyra-citation-badge-accent` / `--lyra-citation-badge-bg` /
+`--lyra-citation-badge-border` (internal per-status accent variables, not typically overridden
+directly — set instead by the `:host([status=...])` rules), plus shared tokens
+`--lyra-color-text-quiet`, `--lyra-color-success` / `-success-quiet`, `--lyra-color-warning` /
+`-warning-quiet`, `--lyra-color-danger` / `-danger-quiet`, `--lyra-radius`, `--lyra-color-surface`,
+`--lyra-color-border`, `--lyra-shadow`, `--lyra-space-s`/`-m`, `--lyra-transition-fast`,
+`--lyra-focus-ring-*`.
+
+**Optional peer deps:** none.
+
+```html
+<p>
+  Revenue grew 12% year over year
+  <lyra-citation-badge index="1" status="verified" source-id="doc-1">
+    <strong>annual_report.pdf</strong> — "Revenue grew 12% year over year, driven primarily by..."
+  </lyra-citation-badge>.
+</p>
+<script type="module">
+  document.addEventListener('lyra-citation-activate', (e) => {
+    document.querySelector(`lyra-source-card[source-id="${e.detail.sourceId}"]`)
+      ?.scrollIntoView({ behavior: 'smooth', block: 'center' });
+  });
+</script>
+```
+
+The popover is positioned with the same internal `place()` helper (`top-start` placement) that
+`<lyra-tool-call-chip>` uses for its own detail tooltip, and never traps focus — it's supplementary
+preview content, not a modal, so Tab continues past the badge normally even while the popover happens
+to be visible from a mouse hover. Hovering and focus are tracked as independent "keep it open"
+reasons (mirroring `<lyra-toast-item>`'s hovering/focused pair), so the pointer leaving while the
+badge still holds keyboard focus doesn't schedule a hide the focus is still holding open. There's a
+200ms grace period before a hover/focus-out actually hides the popover, so moving the pointer from
+the badge into the popover itself (to select/copy its text) doesn't make it vanish mid-move; Escape
+and blur (Tab away) close it immediately instead, with no delay.
+
+Status coloring follows a semantic scheme: `verified`/`high` use the success tones (a claim that's
+been checked, or the model is confident in); `medium`/`low` use warning tones; `unverified` uses the
+*danger* tone — deliberately distinct from `low`, since "hasn't been checked at all" is a different
+(arguably riskier) claim than "checked but uncertain". `default` renders as plain neutral text with
+no background tint, for citations that carry no confidence/verification signal at all.
+
+**Known gotchas:**
+- Enter and Space are given distinct meanings (Enter = activate via native `<button>` click, Space =
+  open) — Space's native click-on-keyup is pre-empted with `preventDefault()` on keydown so it fires
+  `lyra-citation-open` instead of triggering a second `lyra-citation-activate`.
+- Escape closes the popover but calls `stopPropagation()`, so it won't also close a surrounding
+  `<lyra-dialog>` that has its own Escape-to-close handler.
+- The preview slot's presence is tracked in JS (`hasPreviewSlot`), not via CSS `:empty` — the
+  `[part="popover"]` always contains a literal `<slot>` child, so `:empty` would never match even
+  with nothing assigned.
+
+---
+
+## `lyra-source-list` / `lyra-source-card`
+
+A collapsible "Sources" panel for one chat message (`lyra-source-list`) that groups a set of
+`lyra-source-card` entries. First-party invention (no Web Awesome equivalent). Cards are meant to be
+direct light-DOM children of the list (plain composition — no `.items` array prop, the same shape
+`<lyra-split>`'s panels take), though `lyra-source-card` renders and functions fine standalone.
+
+### `lyra-source-list`
+
+**Properties:**
+- `expanded: boolean = false` (reflected) — whether the card list is currently shown. Starts
+  collapsed by default so a message's sources don't eat vertical space until asked for.
+- `label: string = ''` — header text used when `label-plural` isn't set, e.g. `"Sources"`.
+- `labelPlural: string = ''` (attribute `label-plural`) — fully consumer-built, already-pluralized
+  header summary, e.g. `"3 sources"` or `"1 source"`; this component never counts or pluralizes on
+  its own. Takes precedence over `label` when both are set. If neither is set, the header falls back
+  to the literal word `"Sources"`.
+
+**Getters:** `sourceCount: number` — read-only, live-updated count of the currently-slotted children,
+handy for building a `label-plural` string reactively, e.g. `` list.labelPlural = `${list.sourceCount} sources` ``.
+
+**Events:** `lyra-toggle` (`detail: { expanded: boolean }`) — the header was activated, expanding or
+collapsing the list.
+
+**Slots:** default — `<lyra-source-card>` elements (or any content, though the card pairing is the
+intended usage).
+
+**CSS parts:** `base` (outer container), `header` (the clickable `<button>` toggling `expanded`),
+`toggle` (the chevron indicator inside the header), `list` (wrapper around the default slot, `hidden`
+while collapsed).
+
+**Themeable custom properties:** shared tokens only — `--lyra-color-border`, `--lyra-color-surface`,
+`--lyra-color-text`, `--lyra-color-brand` / `-brand-quiet`, `--lyra-radius`, `--lyra-space-xs`/`-s`/
+`-m`, `--lyra-transition-fast`, `--lyra-focus-ring-*`.
+
+**Optional peer deps:** none.
+
+### `lyra-source-card`
+
+**Properties:**
+- `sourceId: string = ''` (attribute `source-id`) — stable identifier matching a
+  `<lyra-citation-badge>` elsewhere on the page.
+- `title: string = ''` — the source's display title, e.g. a filename. Falls back to `"Untitled
+  source"` when empty.
+- `page?: string | number` — optional page reference, e.g. `12` or `"iv"`, rendered as-is (never
+  parsed/validated as a number), appended to the title as `" — p. {page}"`.
+- `href?: string` — optional URL, echoed back (unopened) in `lyra-open`'s detail.
+
+**Events:**
+- `lyra-expand` (`detail: { sourceId: string; expanded: boolean }`) — the per-card "Show
+  more"/"Show less" toggle was activated. Unrelated to the parent `lyra-source-list`'s own
+  expand/collapse, which only ever hides/shows the *set* of cards, never a single card's own content.
+- `lyra-open` (`detail: { sourceId: string; href?: string }`) — the title was activated. This
+  component never navigates on its own (a controlled component, the same convention
+  `<lyra-tool-call-chip>`'s `lyra-tool-chip-select` follows); a listener decides what "open" means.
+
+**Slots:** `excerpt` (a short preview, always visible), `full` (the complete source text/chunk,
+hidden behind the "Show more"/"Show less" toggle — when left empty, no toggle renders at all).
+
+**CSS parts:** `base` (outer container), `title` (the clickable title/page heading, a `<button>`),
+`excerpt` (wrapper around the `excerpt` slot), `full` (wrapper around the `full` slot, `hidden` while
+collapsed), `toggle` (the "Show more"/"Show less" button — only rendered when the `full` slot has
+content).
+
+**Themeable custom properties:** shared tokens only — `--lyra-color-border`, `--lyra-color-surface`,
+`--lyra-color-text` / `-text-quiet`, `--lyra-color-brand`, `--lyra-radius`, `--lyra-space-xs`/`-s`,
+`--lyra-focus-ring-*`.
+
+**Optional peer deps:** none.
+
+```html
+<lyra-source-list label-plural="2 sources">
+  <lyra-source-card source-id="doc-1" title="annual_report.pdf" page="12">
+    <span slot="excerpt">Revenue grew 12% year over year...</span>
+    <span slot="full">Revenue grew 12% year over year, driven primarily by...</span>
+  </lyra-source-card>
+  <lyra-source-card source-id="doc-2" title="q3_notes.md">
+    <span slot="excerpt">No matching full-text chunk for this source.</span>
+  </lyra-source-card>
+</lyra-source-list>
+<script type="module">
+  // Elsewhere, a <lyra-citation-badge>'s activation handler can scroll to and
+  // highlight the matching card -- neither component needs extra API surface
+  // for that, only source-id to be targeted by:
+  document.addEventListener('lyra-citation-activate', (e) => {
+    const card = document.querySelector(`lyra-source-card[source-id="${e.detail.sourceId}"]`);
+    card?.scrollIntoView({ behavior: 'smooth', block: 'center' });
+  });
+</script>
+```
+
+`lyra-source-list` removes the card list from the accessibility tree (not just visually hides it)
+while collapsed, via the native `hidden` attribute on `[part="list"]` — a screen reader user tabbing
+past the header never lands on off-screen source cards they can't currently see. Both components
+track slot presence in JS state (`slottedCount` on the list, `hasFullSlot` on the card) rather than
+relying on CSS `:empty`, since a `[part]` wrapper always contains a literal `<slot>` child regardless
+of assigned content; both also reconcile that state in `firstUpdated()` as a fallback for slot-
+forwarding scenarios or engines that don't fire `slotchange` for content already present at parse
+time.
+
+**Known gotchas:**
+- This library has no built-in i18n/pluralization (the same stance `<lyra-empty>`'s plain
+  `description` prop takes) — `lyra-source-list`'s header text is entirely consumer-supplied via
+  `label`/`label-plural`; there's no automatic "N sources" string generation beyond the literal
+  `"Sources"` fallback.
+- `lyra-source-card`'s own expand/collapse (`full` slot, `lyra-expand` event) is completely
+  independent of the parent list's `expanded`/`lyra-toggle` — collapsing the list doesn't reset an
+  individual card's `fullExpanded` state, and there is no cross-talk between the two components at
+  all beyond DOM nesting.
+
+---
+
+## `lyra-app-rail`
+
+A responsive navigation rail that adapts across three presentations as the *viewport* narrows (not
+this element's own inline size): `'full'` (nav items show icon + label, inline), `'icon-only'` (a
+narrower inline rail, icons only), and `'mobile'` (hidden behind a toggle button; opening it shows a
+focus-trapped floating overlay over the page). First-party invention (no Web Awesome equivalent).
+Breakpoints are viewport-width `matchMedia()` queries against `icon-only-breakpoint`/
+`mobile-breakpoint`, not a `ResizeObserver` on this element — presentation tracks the actual device/
+window width the way a native OS shell's navigation does, not however much horizontal space a
+particular layout happens to give it. `[part="base"]` (the inline `'full'`/`'icon-only'`
+presentation) and `[part="panel"]` (the mobile overlay) are the *same* element promoted in place
+across modes (mirrors `<lyra-widget>`'s fullscreen mode) — never both at once, and slotted nav
+content is never duplicated.
+
+**Properties:**
+- `mode: AppRailMode` (custom accessor, reflected) — the getter always returns one of the three real
+  modes (`'full'|'icon-only'|'mobile'`), never `'auto'`. The setter accepts
+  `AppRailModeInput` (`AppRailMode | 'auto'`): assigning `'full'`/`'icon-only'`/`'mobile'` forces
+  that mode and stops the element responding to breakpoint changes; assigning the write-only
+  sentinel `'auto'` releases the force and immediately re-syncs to the current viewport width,
+  resuming automatic tracking. Settable via the `mode` attribute too (`mode="icon-only"`,
+  `mode="auto"`).
+- `iconOnlyBreakpoint: string = '960px'` (attribute `icon-only-breakpoint`) — any valid CSS length,
+  used directly in a `(max-width: ...)` media query; below it the rail switches from `'full'` to
+  `'icon-only'`.
+- `mobileBreakpoint: string = '600px'` (attribute `mobile-breakpoint`) — same mechanism; below it the
+  rail switches from `'icon-only'` to `'mobile'`. Should be smaller than `iconOnlyBreakpoint` to
+  produce all three states as the viewport narrows.
+- `open: boolean = false` (reflected) — whether the mobile floating overlay is shown. Only meaningful
+  while `mode` is `'mobile'` — the value is preserved (not reset) while another mode is active, but
+  no overlay chrome renders until `mode` is `'mobile'` again. Set this directly, or use the built-in
+  toggle button — there is no separate `show()`/`hide()` pair.
+- `label: string = 'Navigation'` — accessible name for the rail's navigation landmark, and for its
+  dialog role while the mobile overlay is open.
+
+**Events:** `lyra-mode-change` (`detail: AppRailModeChangeDetail` = `{ mode: AppRailMode }`; the
+effective mode changed, whether from a breakpoint crossing or an explicit `mode` assignment — not
+fired for a redundant reassignment to the mode already in effect), `lyra-toggle`
+(`detail: AppRailToggleDetail` = `{ open: boolean }`; the mobile overlay opened or closed — via the
+built-in toggle button, Escape, a backdrop click, a nav-item click while open, or a breakpoint/forced
+mode change leaving `'mobile'` while open — not fired when a consumer sets `open` directly).
+
+**Slots:** default (nav items — generic slotted content, e.g. `<a>`/`<button>` elements the consumer
+builds with its own icon+label structure; clicking anywhere in this slot closes the mobile overlay if
+open), `header` (logo/brand content, shown above the nav items in every mode), `footer` (a trailing
+user/settings trigger, shown below the nav items).
+
+**CSS parts:** `base`, `header`, `nav`, `footer`, `toggle`, `backdrop`, `panel` (`base`/`panel` are
+mutually exclusive on the same underlying element — see above).
+
+**Themeable custom properties:** `--lyra-app-rail-width` (default `15rem` — the inline rail width in
+`'full'` mode), `--lyra-app-rail-icon-width` (default `4rem` — the inline rail width in `'icon-only'`
+mode), `--lyra-app-rail-mobile-width` (default `18rem`, capped at `85vw` — the mobile overlay panel
+width), `--lyra-app-rail-overlay-color` (default `rgb(0 0 0 / 0.5)` — the mobile backdrop scrim
+color; component-specific since no shared token exists), plus shared tokens (`--lyra-color-border`,
+`--lyra-color-surface`, `--lyra-color-text`, `--lyra-color-brand`, `--lyra-color-brand-quiet`,
+`--lyra-space-*`, `--lyra-radius`, `--lyra-shadow`, `--lyra-icon-button-size`,
+`--lyra-focus-ring-*`, `--lyra-transition-base`).
+
+**Optional peer deps:** none.
+
+```html
+<lyra-app-rail label="Main navigation" icon-only-breakpoint="960px" mobile-breakpoint="600px">
+  <span slot="header"><img src="/logo.svg" alt="Acme" /></span>
+  <a href="/inbox" aria-label="Inbox"><svg aria-hidden="true">...</svg><span>Inbox</span></a>
+  <a href="/settings" aria-label="Settings"><svg aria-hidden="true">...</svg><span>Settings</span></a>
+  <span slot="footer"><button>Profile</button></span>
+</lyra-app-rail>
+```
+```ts
+rail.mode = 'icon-only'; // force a presentation regardless of viewport width
+rail.mode = 'auto';      // release the force, resume live breakpoint tracking
+```
+
+The package root also exports a pure `computeAppRailMode(iconOnlyMatches: boolean, mobileMatches:
+boolean): AppRailMode` resolver (plus the `AppRailMode`/`AppRailModeInput`/`AppRailModeChangeDetail`/
+`AppRailToggleDetail` types) — the same logic the element's internal `matchMedia` listeners call,
+exposed standalone so a consumer can compute or unit-test the same three-state resolution without a
+real browser window. `mobileMatches` wins over `iconOnlyMatches` when both are true (the viewport is
+narrower than both breakpoints at once).
+
+This is its own standalone focus-trapped overlay implementation for the `'mobile'` state
+(`role="dialog"` while open, Escape/backdrop-dismissible, scroll-locking) rather than nesting a
+`<lyra-dialog>` in its shadow template. It's a plain `<div>` with an explicit `role="navigation"`
+(swapping to `role="dialog"` while the overlay is open) rather than a literal `<nav>` tag, since a
+`<nav>`'s implicit role can't be overridden to `role="dialog"` without an `aria-allowed-role`
+violation. In `'icon-only'` mode, slotted nav items lose their visible text label — give each one a
+real accessible name (`aria-label`, visually hidden text, or `title`) regardless, since this
+component only lays out whatever is slotted and can't inspect or fix up a consumer's own markup.
+
+**Known gotchas:**
+- `mode`'s setter accepts the wider `AppRailModeInput` (including the `'auto'` sentinel) but the
+  getter's return type is the narrower `AppRailMode` — assigning `'auto'` is a one-way instruction,
+  not a value read back later; there is no `isForced`-style property to check whether the rail is
+  currently locked to a mode or tracking the viewport.
+- reassigning `icon-only-breakpoint`/`mobile-breakpoint` after first render tears down and rebuilds
+  the `matchMedia` listeners, but does not itself un-force a previously-forced `mode` — if a consumer
+  set `mode = 'icon-only'`, changing the breakpoints won't resume auto-tracking until `mode = 'auto'`
+  is set explicitly.
+- leaving `'mobile'` mode while `open` (via a breakpoint crossing or a forced `mode` reassignment)
+  auto-closes the overlay through the same path as the toggle button, so `lyra-toggle` still fires
+  and the scroll lock/focus trap still release normally — a consumer listening only for explicit
+  toggle-button clicks would miss this closure.
+- the mobile panel is also given `inert` whenever `mode === 'mobile'` and `open` is `false` — it's
+  removed from the accessibility tree and tab order via `inert` at the same time it's hidden visually
+  via `transform: translateX(-100%)`, both applied simultaneously rather than one implying the other.
+- the offscreen slide direction for the mobile panel is flipped for RTL via a `:dir(rtl)` CSS
+  selector (`translateX(100%)`), not through the shared `internal/rtl.ts` JS helper used for pointer/
+  keyboard math elsewhere in this library — a physical `transform` isn't expressible with logical
+  properties, so this one case is handled purely in CSS.
+- a reconnect that preserves the same element instance (e.g. a drag-and-drop reparent) restores the
+  scroll lock and the Tab-trap `keydown` listener if the overlay was still active across the move —
+  `disconnectedCallback`/`connectedCallback` fire back-to-back with no update in between, so
+  `willUpdate()` alone wouldn't otherwise notice.
+
+---
+
+## `lyra-responsive-panel`
+
+The same slotted content either docked inline in the page's normal layout flow (desktop) or
+presented as a full-screen/bottom-sheet overlay (mobile), depending on viewport width. First-party
+invention (no Web Awesome equivalent). Typical uses: a settings panel or a conversation-history
+sidebar that's a permanent docked pane on a wide screen but a modal on a phone.
+
+**Properties:**
+- `open: boolean = false` (reflected) — in the inline presentation this just means visible/mounted;
+  in the overlay presentation this is the actual modal open/closed state.
+- `mode: ResponsivePanelMode = 'auto'` (reflected) — `'auto'` tracks `mobile-breakpoint` live;
+  `'inline'`/`'overlay'` force that presentation regardless of viewport width.
+- `variant: ResponsivePanelVariant = 'fullscreen'` (reflected) — only affects the overlay
+  presentation's visual treatment: `'fullscreen'` covers the whole viewport; `'bottom-sheet'` slides
+  up from the bottom and doesn't cover the full height. Has no visual effect while the effective
+  presentation resolves to `'inline'`.
+- `label: string = ''` — accessible name for the overlay presentation's `role="dialog"`. Unused in
+  the inline presentation, which has no dialog semantics to name.
+- `mobileBreakpoint: string = '768px'` (attribute `mobile-breakpoint`) — CSS length passed to
+  `matchMedia` as `(max-width: <this>)` to decide, in `mode="auto"`, whether the effective
+  presentation is `'overlay'` (below/at this width) or `'inline'` (above it).
+
+**Methods:** `close(reason: ResponsivePanelCloseReason = 'api'): void` — closes the panel (sets
+`open = false`), emits `lyra-close` with `reason`, and — only in the overlay presentation — returns
+focus to whichever element triggered the open. No-op if already closed. Built-in overlay triggers
+call this with `'escape'`/`'backdrop'`; a consumer's own close affordance (a footer button, a docked
+panel's own toggle) should call it directly with its own reason string.
+
+**Events:** `lyra-close` (`detail: ResponsivePanelCloseReason` = `'escape'|'backdrop'|'api'|string`;
+fired by the overlay presentation's built-in dismiss triggers — Escape, backdrop click — and by any
+`close()` call, in either presentation; a plain `open = false` property write does **not** fire it,
+only going through `close()` counts as a dismissal), `lyra-mode-change`
+(`detail: ResponsivePanelModeChangeDetail` = `{ mode: ResponsivePanelEffectiveMode }`; fired whenever
+the *effective* mode — not the `mode` prop's possibly-`'auto'` literal value — changes between
+`'inline'` and `'overlay'`; never fired on the initial render, only for a live change thereafter).
+
+**Slots:** default (the panel body), `header` (optional header content, rendered above the body),
+`footer` (optional footer content, e.g. action buttons, rendered below the body).
+
+**CSS parts:** `base`, `backdrop`, `panel`, `header`, `body`, `footer` (`backdrop` is only rendered
+in the overlay presentation).
+
+**Themeable custom properties:** `--lyra-responsive-panel-overlay-color` (default
+`rgb(0 0 0 / 0.5)` — the overlay presentation's backdrop scrim color; component-specific since no
+shared token exists), plus shared tokens (`--lyra-color-border`, `--lyra-color-surface`,
+`--lyra-space-*`, `--lyra-radius`, `--lyra-shadow`).
+
+**Optional peer deps:** none.
+
+```html
+<lyra-responsive-panel id="settings-panel" label="Settings" variant="bottom-sheet" mobile-breakpoint="768px">
+  <span slot="header"><h2>Settings</h2></span>
+  <div>Panel body content — a form, a list, anything.</div>
+  <span slot="footer"><button onclick="document.getElementById('settings-panel').close()">Done</button></span>
+</lyra-responsive-panel>
+```
+
+Breakpoint detection uses `matchMedia('(max-width: ' + mobileBreakpoint + ')')`, re-evaluated live
+while connected — resizing/rotating a device that crosses the breakpoint while `mode="auto"` (the
+default) updates the effective presentation without unmounting or re-creating the slotted content:
+inline and overlay presentation share the exact same shadow DOM structure (only a CSS class, and the
+overlay-only `role`/`aria-modal` attributes and backdrop element, differ), so lit-html's diffing
+keeps `[part="body"]` and its `<slot>` as the same DOM node across the transition — scroll position
+and focus inside the slotted content survive it for free. The one exception is focus: crossing the
+breakpoint while already open does *not* forcibly move focus into the panel (unlike a genuine `open`
+transition, which does) — doing so on a resize could yank focus away from an input the user is
+actively typing into inside the now-newly-modal panel. The overlay presentation duplicates
+`<lyra-dialog>`'s `role="dialog"` + focus-trap + Escape/backdrop-dismiss + scroll-lock mechanics
+locally rather than nesting a `<lyra-dialog>` inside this component's shadow DOM.
+
+The package root also exports the pure `resolveEffectiveMode(mode: ResponsivePanelMode,
+belowBreakpoint: boolean): ResponsivePanelEffectiveMode` resolver — renamed on export to
+`resolveResponsivePanelEffectiveMode` to avoid a name collision — alongside the
+`ResponsivePanelMode`/`ResponsivePanelEffectiveMode`/`ResponsivePanelVariant`/
+`ResponsivePanelCloseReason`/`ResponsivePanelModeChangeDetail` types. It's the same logic the
+element's internal `matchMedia` listener calls: `'inline'`/`'overlay'` pass straight through
+unchanged; `'auto'` resolves to `'overlay'` when `belowBreakpoint` is true, `'inline'` otherwise —
+exposed standalone so a consumer can compute or unit-test the same resolution without a real browser
+window.
+
+**Known gotchas:**
+- setting `open = true`/`open = false` directly does not fire `lyra-close` and does not run the
+  focus-return-to-trigger logic either — only calling `close()` does both; a consumer that toggles
+  the property directly instead of calling `close()` silently loses both behaviors.
+- crossing the breakpoint while the panel is already open does not move focus into it, unlike a
+  genuine `open` transition — see above; don't rely on a resize alone to place initial focus.
+- `variant="bottom-sheet"` has no visible effect at all while the effective presentation is
+  `'inline'` — it only changes the overlay presentation's anchoring/height.
+- a reconnect that preserves the same element instance (e.g. a drag-and-drop reparent) restores the
+  scroll lock and the Tab-trap `keydown` listener if overlay chrome was still active across the move
+  — `disconnectedCallback`/`connectedCallback` fire back-to-back with no update in between, so
+  `willUpdate()` alone wouldn't otherwise notice.
+- the exported pure function is named `resolveEffectiveMode` in the component module but re-exported
+  from the package root as `resolveResponsivePanelEffectiveMode` — importing the un-prefixed name
+  from `@aceshooting/lyra-ui` will fail.
+
+---
+
+## `lyra-mention-popover`
+
+A caret-anchored, keyboard-navigable popover for `@`-mention and `/`-slash-command autocomplete
+inside a plain-text `<textarea>`/`<input>` the host owns. First-party invention (no Web Awesome
+equivalent). It never takes DOM focus itself — the host's own input keeps focus, and this
+component conveys the active row via `activeDescendantId` for the host to apply as its own
+input's `aria-activedescendant`, the same pattern `<lyra-select>`/`<lyra-combobox>` use for their
+own listbox.
+
+**Properties:**
+- `anchor?: HTMLElement` (attribute: false) — the element to position the popup relative to. A
+  plain `<textarea>` or single-line text `<input type="text"|"search">` gets caret-precise
+  positioning; any other element anchors the whole popup under that element's own box.
+- `items: MentionItem[] = []` (attribute: false) — the full candidate set, pre-`query`-filtering.
+- `query: string = ''` — the text typed since the trigger character; drives the built-in filtering
+  (see `filter`).
+- `open: boolean = false` (reflected)
+- `filter: MentionFilter | null = null` (attribute: false) — overrides the built-in
+  case-insensitive `label`/`description` substring match entirely.
+- `emptyText: string = 'No matches'` (attribute `empty-text`)
+- `label: string = 'Suggestions'` — accessible name for the `role="listbox"` popup.
+- `filteredItems: MentionItem[]` — read-only getter; `items` filtered by `query` via `filter` (or
+  the built-in default). Empty `query` returns `items` unfiltered.
+- `activeDescendantId: string | null` — read-only getter; the `id` of the currently-highlighted
+  row, or `null` while closed or when `filteredItems` is empty.
+- `listboxId: string` — read-only getter; the `id` of the `role="listbox"` element, for a host that
+  also wants to wire `aria-controls`.
+
+**Methods:** `handleKeyDown(e: KeyboardEvent): boolean` — the host's own text-control `keydown`
+handler calls this while the popover is open. Handles `ArrowDown`/`ArrowUp` (moves the highlight),
+`Enter`/`Tab` (commits the highlighted row, no-op that returns `false` if nothing is highlighted),
+and `Escape` (closes with no selection). Returns `true` when the key was intercepted
+(`preventDefault()` already called) and the host should not also act on it.
+
+**Exported types:** `MentionItem { id: string; label: string; description?: string; icon?: string
+}`; `MentionFilter = (item: MentionItem, query: string) => boolean`; `MentionSelectDetail { id:
+string; label: string }`.
+
+**Events:** `lyra-mention-select` (`detail: MentionSelectDetail`, `{ id, label }` of the row that
+was committed via Enter/Tab/click), `lyra-mention-close` (no detail payload —
+`this.emit('lyra-mention-close')` is called with no second argument, so `event.detail` is `null`,
+not `undefined`; fires on Escape or any other `open: true -> false` transition, but never for the
+close that immediately follows a `lyra-mention-select` commit, and never for markup that simply
+renders `open="false"` on first paint)
+
+**Slots:** none.
+
+**CSS parts:** `listbox`, `option`, `option-icon` (when `icon` is set), `option-label`,
+`option-description` (when `description` is set), `empty`
+
+**Themeable custom properties:** shared tokens only — `--lyra-space-xs`/`-s`/`-m` (popup padding,
+row padding/gap), `--lyra-color-surface`/`-border` (popup background/border), `--lyra-radius`
+(popup and row corners), `--lyra-shadow` (popup elevation), `--lyra-transition-fast` (open/close
+transition), `--lyra-color-brand-quiet` (active-row background), `--lyra-color-brand` (selected-row
+text), `--lyra-color-text-quiet`/`--lyra-color-text` (description text, full-contrast on the active
+row).
+
+**Optional peer deps:** none.
+
+```html
+<textarea id="composer"></textarea>
+<lyra-mention-popover id="mentions" label="People" empty-text="No matches"></lyra-mention-popover>
+<script type="module">
+  const textarea = document.getElementById('composer');
+  const popover = document.getElementById('mentions');
+
+  textarea.addEventListener('keydown', (e) => {
+    if (popover.open && popover.handleKeyDown(e)) return; // consumed
+  });
+  textarea.addEventListener('input', () => {
+    popover.anchor = textarea;
+    popover.items = [
+      { id: 'ada', label: 'Ada Lovelace', description: 'Engineering', icon: '👩‍💻' },
+      { id: 'grace', label: 'Grace Hopper', description: 'Engineering' },
+    ];
+    popover.query = 'a'; // detected since the trigger character
+    popover.open = true;
+  });
+
+  popover.addEventListener('lyra-mention-select', (e) => {
+    // splice `${e.detail.label}` into the textarea at the trigger offset
+  });
+</script>
+```
+
+Integration is entirely the host's responsibility: detect a mention/command trigger in the host's
+own `input` handling, set `anchor`/`items`/`query` and flip `open = true`, forward every `keydown`
+through `handleKeyDown()` while open, and keep the host's own input's `aria-activedescendant` (and
+optionally `aria-controls`, via `listboxId`) in sync with `activeDescendantId`. Setting `open =
+false` whenever the query stops looking like an active mention context (a space typed, the trigger
+deleted, the input blurred, …) is also the host's job — `lyra-mention-close` fires automatically
+from that, there is no separate "tell it to close" call needed.
+
+Positioning measures exactly where the caret currently paints via a hidden-mirror-element technique
+(`caretClientRect()`) and positions against that single point with `internal/positioner.js`'s
+`place()`, so the popup tracks the caret rather than sitting under the whole textarea. Re-measures
+automatically only on an `anchor` or `query` change while open (a keystroke moves the caret, so a
+fresh `query` is the proxy for "the caret may have moved").
+
+**Known gotchas:**
+- The popover opens pre-highlighted on the top match (index 0), unlike `<lyra-combobox>`'s own
+  listbox which opens with nothing highlighted (`-1`) — a bare Enter right after opening commits
+  immediately.
+- Caret-precise positioning only applies to a plain `<textarea>` or single-line text
+  `<input type="text"|"search">`; any other `anchor` element, or a text control whose caret rect
+  can't be measured (e.g. `display: none`), silently falls back to whole-element anchoring against
+  `anchor` itself.
+- A caret that moves for a reason other than typing (e.g. a mouse click elsewhere in the text while
+  the popover happens to still be open) is not separately tracked — force a re-measure by toggling
+  `open` or reassigning `anchor`.
+- `activeIndex` resets to `0` whenever `query` or `items` changes, but not when only `anchor`
+  changes — reassigning `anchor` alone preserves whatever row was last highlighted.
+
+---
+
+## `lyra-streaming-text`
+
+A token-coalescing incremental text renderer for streaming assistant output, with an optional
+blinking cursor and auto-detected Markdown rendering. First-party invention (no Web Awesome
+equivalent). The host is expected to assign the *entire* current text on every update to `content`,
+not a delta — this component does no accumulation or ordering of its own.
+
+**Properties:**
+- `content: string = ''` — the full current text so far.
+- `streaming: boolean = false` (reflected) — shows the blinking cursor after the rendered text;
+  reflects so a host can also target `lyra-streaming-text[streaming]` in CSS.
+- `coalesceMs: number = 50` (attribute `coalesce-ms`) — trailing-edge coalesce window, in ms, for
+  `content` updates (see prose below).
+- `markdown?: boolean` (attribute `markdown`, tri-state via a custom `ComplexAttributeConverter`) —
+  `undefined` (attribute absent, the default) auto-detects via `looksLikeMarkdown`; the attribute
+  present with no value or `="true"` forces `true`; `markdown="false"` forces `false`. An explicit
+  `true`/`false` always wins over the heuristic.
+
+**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
+`true` on the first match. Used internally whenever `markdown` is left unset; exported standalone
+so the heuristic is directly testable without going through the component's render cycle. None of
+the patterns need to be airtight — a false positive just routes ordinary prose harmlessly through
+`<lyra-markdown>`; a false negative just shows literal `**`/backticks/etc. as plain text until more
+of the stream arrives.
+
+**Events:** none.
+
+**Slots:** none — content renders from `content`, not a slot.
+
+**CSS parts:** `base`, `cursor` (only rendered while `streaming` is `true`)
+
+**Themeable custom properties:** `--lyra-streaming-text-cursor-width` (default `0.125rem` — the
+cursor bar's inline size; component-specific, since no shared "inline cursor bar" token exists,
+the same pattern `<lyra-typing-indicator>`'s own `--lyra-typing-cursor-width`/`-height` use), plus
+shared `--lyra-space-xs` (cursor's `margin-inline-start`) and `--lyra-transition-base` (blink
+animation cycle length).
+
+**Optional peer deps:** none — internally imports and auto-registers `<lyra-markdown>` for
+Markdown-mode rendering (a side-effect import; the host never needs to import or register it
+itself).
+
+```html
+<lyra-streaming-text id="out" coalesce-ms="80" streaming></lyra-streaming-text>
+<script type="module">
+  const out = document.getElementById('out');
+  let text = '';
+  for await (const token of tokenStream) {
+    text += token;
+    out.content = text; // always the full string so far, never a delta
+  }
+  out.streaming = false; // forces the final chunk through immediately; cursor disappears
+</script>
+```
+
+Token-by-token streaming can update `content` far faster than a human can usefully perceive a
+re-render, so updates funnel through `Announcer` (`../../internal/announcer.js`), reused here
+purely as a generic "coalesce rapid calls, flush the latest" timing primitive — with none of that
+class's usual DOM/ARIA plumbing. Within any `coalesce-ms` window, only the *last* `content` value
+assigned actually reaches the rendered DOM. Two cases always bypass the throttle and flush
+immediately: the very first `content` assignment after mount, and any transition of `streaming`
+from `true` to `false`, so the final chunk of a finished stream can never be left stranded mid-
+window.
+
+Rendering itself is never reimplemented here: Markdown mode composes `<lyra-markdown>` directly,
+forwarding this component's own `streaming` through as that component's `streaming` hint prop;
+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
+below the rendered content instead of attempting to splice into whatever nested block Markdown
+happens to end with.
+
+**Known gotchas:**
+- `content` must always be the complete string so far, never a delta — this component does no
+  accumulation of its own.
+- Only the very *first* `content` assignment after mount bypasses `coalesceMs` — every later
+  assignment is throttled normally until `streaming` flips to `false`.
+- `markdown="false"` (any string value other than exactly `"false"` is treated as `true` by the
+  converter) forces plain-text mode even if the text obviously contains Markdown syntax.
+- Purely presentational: no events, and it does not announce anything to assistive tech itself — a
+  host that needs streamed text announced needs `<lyra-live-region>` for that (e.g. composed inside
+  `<lyra-chat-message>`).
+
+---
+
+## `lyra-thinking-panel`
+
+A collapsible panel for an AI agent's intermediate reasoning/"thinking" transcript, kept visually
+and semantically distinct from its final response. First-party invention (no Web Awesome
+equivalent). Same collapsible header-button-plus-region shape as `<lyra-source-list>`; the default
+slot is entirely free-form (a consumer-composed `<lyra-streaming-text>`, `<lyra-markdown>`, or
+plain text) — this component has no dependency on either.
+
+**Properties:**
+- `label: string = 'Thinking'`
+- `expanded: boolean = false` (reflected) — starts collapsed, matching `<lyra-source-list>`'s
+  default.
+- `mode: 'live' | 'post-hoc' = 'live'` (reflected) — `'live'` while reasoning is actively streaming
+  in; `'post-hoc'` once it's complete and being reviewed after the fact. Drives two concrete
+  behavior differences, see prose below.
+- `durationMs?: number` (attribute `duration-ms`) — how long the reasoning took. Omitted entirely
+  (nothing rendered in `'post-hoc'`, a pulsing placeholder in `'live'`) while unset.
+
+**Methods:** `scrollToBottom(): void` — scrolls `[part="body"]` to its current bottom immediately
+(no smooth-scroll animation). Safe to call directly, e.g. from a host that wants to force a
+jump-to-latest action of its own.
+
+**Events:** `lyra-toggle` (`detail: { expanded: boolean }`, same event name and shape as
+`<lyra-source-list>`'s own `lyra-toggle`) — fired whenever the header button is activated.
+
+**Slots:** default (the reasoning/thinking content; entirely free-form)
+
+**CSS parts:** `base`, `header`, `label`, `duration`, `toggle`, `body`
+
+**Themeable custom properties:** `--lyra-thinking-panel-max-block-size` (default `16rem` —
+consumer-overridable cap on how tall `[part="body"]` grows before it scrolls internally; not
+exposed as a component property since it's a pure layout knob, not something a template branches
+on), plus shared `--lyra-color-border`/`-surface`/`-text`/`-text-quiet`/`-brand`/`-brand-quiet`,
+`--lyra-space-xs`/`-s`/`-m`, `--lyra-radius`, `--lyra-focus-ring-width`/`-color`/`-offset`,
+`--lyra-transition-fast`/`-base`.
+
+**Optional peer deps:** none.
+
+```html
+<lyra-thinking-panel label="Reasoning" mode="live" expanded>
+  <lyra-streaming-text content="Considering the user's constraints…" streaming></lyra-streaming-text>
+</lyra-thinking-panel>
+
+<lyra-thinking-panel label="Reasoning" mode="post-hoc" duration-ms="4200">
+  <p>Finished reasoning, collapsed by default.</p>
+</lyra-thinking-panel>
+```
+
+`mode` drives two concrete behavior differences, not just a styling hook. **Header hint:** while
+`duration-ms` is unset, `'live'` shows a pulsing "Thinking…" placeholder in `[part="duration"]`;
+`'post-hoc'` shows nothing there. Once `duration-ms` is set, both modes show the same static
+"Thought for …" text. **Auto-scroll:** only `'live'` mode auto-follows new content appended to the
+default slot while `expanded`; `'post-hoc'` never scrolls on its own.
+
+Live-mode auto-scroll ("stick to bottom") is the classic chat-transcript convention: while
+`mode="live"` and `expanded`, new content keeps the panel scrolled to its latest line — unless the
+user has manually scrolled up to re-read earlier content (tracked via a `scroll` listener on
+`[part="body"]`: every user-driven scroll records whether the body was left within 48px of its own
+max scroll position, and only a mutation that arrives while that's still true triggers a follow-up
+scroll). Opening an already-`'live'` panel always resets this to "anchored" and jumps to the latest
+content. New content is detected via a `MutationObserver` on this element's own light DOM
+(`childList`+`subtree`+`characterData`), not `slotchange`, since streamed reasoning typically
+appends chunks to an existing node's `textContent` rather than re-slotting a whole new element per
+token; scroll-to-bottom calls are coalesced to at most one per animation frame under a fast token
+stream.
+
+**Known gotchas:**
+- The `MutationObserver` only watches this element's own light-DOM subtree — it cannot see a
+  mutation that happens entirely inside a slotted custom element's own shadow root (e.g. a
+  `<lyra-markdown>` re-rendering its shadow tree after a `content` change). A slotted element whose
+  own internal updates should drive auto-scroll needs to append/mutate visible light-DOM text
+  itself (as `<lyra-streaming-text>` does), or the host can call `scrollToBottom()` directly.
+- Switching `mode` from `'post-hoc'` to `'live'` while the panel is already `expanded` does not by
+  itself jump to the bottom or reset stickiness — only an `expanded` transition to `true` while
+  `mode === 'live'` does that.
+- The sticky-bottom flag starts `true` internally, so a panel that mounts already `expanded` and
+  `mode="live"` follows its very first content mutation even before any `scroll` event has fired.
+
+---
+
+## `lyra-generation-status`
+
+A compact, ticking status readout shown alongside an in-progress AI response: elapsed time, token
+count, and token-throughput, plus a built-in Stop button. First-party invention (no Web Awesome
+equivalent). Renders as e.g. `12.3s · 340 tokens · 27 tok/s [Stop]`.
+
+**Properties:**
+- `active: boolean = false` (reflected) — whether generation is currently in progress. The
+  elapsed-time ticker (a ~1s `setInterval`) runs only while this is `true`.
+- `startedAt?: number` (attribute `started-at`) — epoch-ms timestamp of when generation began.
+  Optional — when unset while `active` is `true`, this component captures `Date.now()` itself the
+  moment `active` becomes `true` and counts from there instead.
+- `tokenCount?: number` (attribute `token-count`) — running token count so far. Omitted from the
+  readout entirely (no `tokens` segment) while unset.
+- `tokensPerSecond?: number` (attribute `tokens-per-second`) — host-computed tokens/sec figure,
+  used as-is when set. When unset, derived from `token-count`/elapsed time instead (see prose).
+- `showStop: boolean = true` (attribute `show-stop`) — whether the built-in Stop button renders at
+  all. **Not reflected**, and its class-field default is `true` — assign `false` via a PROPERTY
+  binding, e.g. `.showStop=${false}` — a `?show-stop=${false}` boolean-attribute binding can never
+  override a `true` default, since removing an attribute that was never present fires no
+  `attributeChangedCallback` (see AGENTS.md).
+
+**Events:** `lyra-stop` (no detail payload — `this.emit('lyra-stop')` is called with no second
+argument, so `event.detail` is `null`, not `undefined`) — fired when the built-in Stop button is
+clicked.
+
+**Slots:** none.
+
+**CSS parts:** `base`, `elapsed` (always rendered, reads `"0.0s"` before the component has ever
+been active), `tokens` (only rendered when `token-count` is set), `throughput` (only rendered when
+a value is available, host-supplied or derived), `stop-button` (only rendered while `show-stop` is
+`true`)
+
+**Themeable custom properties:** shared tokens only — `--lyra-color-text-quiet` (base readout and
+tokens/throughput text color), `--lyra-color-text` (the elapsed segment's higher-contrast color,
+and the stop-button's icon color), `--lyra-space-s` (stop-button margin), `--lyra-icon-button-size`
+(stop-button min sizing, capped at `1.75rem`), `--lyra-color-border`/`-surface`/`-brand`
+(stop-button border/background/hover), `--lyra-focus-ring-width`/`-color`/`-offset`,
+`--lyra-transition-fast`.
+
+**Optional peer deps:** none.
+
+```html
+<lyra-generation-status active started-at="1732000000000" token-count="340" show-stop></lyra-generation-status>
+<script type="module">
+  document.querySelector('lyra-generation-status').addEventListener('lyra-stop', () => {
+    controller.abort(); // stop the host's own generation
+  });
+</script>
+```
+
+This is deliberately a *different* concern than `<lyra-stream-status>`: that component is about
+transport/connection health (idle/connecting/streaming/stalled, heartbeat-aware stall detection),
+while this one is a user-facing metrics readout for a generation both components' hosts typically
+already know is healthily in progress. Neither imports or depends on the other; compose both side
+by side rather than picking one. `tokens-per-second`, when supplied directly, is always used as-is;
+when omitted, this component derives a live figure from `token-count` divided by elapsed seconds,
+but only once at least one full second of elapsed time has accumulated (dividing by a sub-second
+window can produce wildly-swinging early readings, e.g. 3 tokens in 40ms reading as "75 tok/s").
+The elapsed clock is frozen, not reset, once `active` goes `false` — a static "Generated in 12.3s"
+reads better as a completed-state summary than the readout blanking out the instant generation
+ends.
+
+This readout ticks roughly once per second while active, which is exactly the kind of
+high-frequency update `<lyra-live-region>`/`Announcer` exists to *prevent* from being read aloud
+verbatim — this component therefore carries no `role="status"`/`aria-live` of its own and never
+announces anything. A host that wants generation-start/-end announced should pair this with
+something that announces state *transitions* instead. The Stop button gets a normal, always-present
+`aria-label="Stop generating"`, no different from any other icon-only button in this library.
+
+**Known gotchas:**
+- `showStop` defaults to `true` and is not a reflected property — see the property list above for
+  the property-vs-attribute-binding footgun this creates.
+- The derived `tokens-per-second` figure only appears once `elapsedMs >= 1000`; before that, the
+  `throughput` part simply doesn't render — supply `tokens-per-second` yourself for a stable figure
+  from the very first tick.
+- The elapsed-time display is never reset to `"0.0s"` when `active` goes `false` — it freezes at
+  its last value. A host that wants a blank readout between generations must reset `started-at`/
+  `token-count` itself (or unmount/remount the element).
+- `started-at` only re-baselines the ticker at the moment it's read: mounting the component with
+  `active` already `true` but no `started-at` captures `Date.now()` at that first update, not at
+  whatever earlier instant generation may actually have begun.
+
+---
+
+## `lyra-code-block`
+
+Fenced code display with optional lazy syntax highlighting and a copy button. First-party invention
+(no Web Awesome equivalent). No highlighting grammar ships in the component itself — it lazy-loads
+the optional peer dependency `shiki` (see `code-loader.ts`) for the actual tokenizing, and degrades
+to a plain `<pre><code>` when that peer isn't installed or `language` is unset/unrecognized. That
+fallback is the *default* rendering path, not a degraded one: unhighlighted code is perfectly usable,
+and it's what every instance renders at zero extra bytes until shiki resolves.
+
+**Properties:**
+- `code: string = ''` — the raw source text
+- `language: string = ''` — a shiki-recognized language id or alias (e.g. `"javascript"`, `"python"`,
+  `"json"`); when unset, or when shiki doesn't recognize it, the code renders as plain unhighlighted
+  text regardless of whether shiki itself is available
+- `filename: string = ''` — shown in the header, when set
+- `collapsible: boolean = false` (reflected) — shows the collapse/expand chevron button
+- `collapsed: boolean = false` (reflected) — only has a visible effect while `collapsible` is also
+  true
+- `copyable: boolean = true` (reflected) — shows the copy-to-clipboard button (assign `false` via a
+  PROPERTY binding, e.g. `.copyable=${false}` — a `?copyable=${false}` boolean-attribute binding
+  cannot override a true default)
+- `maxHeight: string = ''` (attribute `max-height`) — a CSS length (e.g. `"20rem"`); once set, the
+  code scrolls internally past this height instead of growing the page
+
+**Events:** `lyra-copy` (`detail: { text: string }` — always the raw `code` value, never the
+highlighted HTML, and always fires regardless of whether the actual OS clipboard write succeeded)
+
+**Slots:** none.
+
+**CSS parts:** `base`, `header`, `filename`, `language`, `copy-button`, `toggle`, `body`, `pre`,
+`code`
+
+**Themeable custom properties:** `--lyra-code-block-max-height` (default `none` — the consumer-tunable
+scroll cap; only takes effect once `max-height` is set), `--lyra-code-block-font` (default
+`ui-monospace, SFMono-Regular, Menlo, Consolas, monospace` — no shared `--wa-*`/`--lyra-*` monospace
+token exists to resolve through), plus shared tokens `--lyra-color-border`, `--lyra-radius`,
+`--lyra-color-surface`, `--lyra-space-xs/-s/-m`, `--lyra-font`, `--lyra-color-text-quiet`,
+`--lyra-color-text`, `--lyra-color-brand`/`-brand-quiet`, `--lyra-transition-fast`,
+`--lyra-focus-ring-width/-color/-offset`.
+
+**Optional peer deps:** `shiki` (lazy-loaded and cached once per page by `code-loader.ts`'s
+`loadShikiHighlighter()`, which builds a single `Highlighter` seeded with the bundled `github-light`/
+`github-dark` "dual themes" and *zero* language grammars up front; each `language` a
+`<lyra-code-block>` actually requests is loaded incrementally on first use via
+`loadShikiLanguage()`, and a language id that fails to load once is remembered and never retried. If
+`shiki` isn't installed, `loadShikiHighlighter()` resolves to `null` with a one-time `console.warn`
+and every instance falls back to plain text — install it with `pnpm add shiki` to enable
+highlighting).
+
+```html
+<lyra-code-block
+  language="typescript"
+  filename="sum.ts"
+  collapsible
+  max-height="20rem"
+  .code=${`export function sum(a: number, b: number) {\n  return a + b;\n}`}
+  @lyra-copy=${(e) => console.log('copied', e.detail.text)}
+></lyra-code-block>
+```
+
+A `<lyra-skeleton variant="rect">` placeholder (with `aria-busy="true"` on the host) stands in only
+while shiki itself is loading for the very first time on the page and `language` is set — it is
+deliberately *not* shown again for a later per-language grammar fetch (that's typically fast, and the
+plain-text fallback already reads fine as a placeholder for it). Internally, a shiki `transformer`
+(`partTransformer`) rewrites shiki's generated `<pre>`/`<code>` nodes in a single pass to carry this
+component's own `part="pre"`/`part="code"` hooks and strips shiki's default `tabindex="0"` from
+`<pre>`, since `[part="body"]` is already the single scrollable/focusable region (`role="group"`,
+`tabindex="0"`) for the code area. Dark mode is handled via shiki's own "dual themes" feature: every
+token carries its light color as a plain inline `color`/`background-color` and its dark color in
+`--shiki-dark`/`--shiki-dark-bg` custom properties, which an `!important` media-query rule in
+`code-block.styles.ts` reassigns under `prefers-color-scheme: dark` — the one deliberate exception in
+this component to every other color being a `--lyra-*` token, since these values come from shiki's own
+theme data.
+
+**Known gotchas:**
+- `copyable` defaults to `true` and reflects — see the property note above about overriding it with a
+  property binding, not a boolean-attribute binding.
+- an in-flight per-language grammar load is guarded by an internal token so a `code`/`language` change
+  that arrives before a previous load resolves never applies a stale result — only the load matching
+  the *current* `language` is ever rendered.
+- a malformed `code`/`language` combination that makes shiki's `codeToHtml()` throw falls back to
+  plain text silently, not a blank code block.
+- the "Copied!" label reverts to "Copy" after a fixed 1500ms, regardless of whether the clipboard
+  write actually succeeded — `navigator.clipboard` is absent in insecure contexts/older browsers, and
+  `lyra-copy` still fires either way.
+
+---
+
+## `lyra-tool-approval-dialog`
+
+A human-in-the-loop gate: presents one proposed tool/function call (`toolName` + `args`) and blocks an
+agent from executing it until a person explicitly approves or denies it, with an optional inline
+"edit the arguments before approving" step. First-party invention (no Web Awesome equivalent). It is
+its own standalone overlay implementation (`role="dialog"`, focus-trapped, Escape/backdrop-dismissible,
+scroll-locking) rather than nesting `<lyra-dialog>` in its shadow template, so it has no dependency on
+the general-purpose dialog component.
+
+Approve/Deny/Edit are built-in chrome, not a `footer` slot a consumer must assemble — there is exactly
+one correct action set for "approve this call". The `footer` slot is offered only for *supplementary*
+content alongside those buttons (e.g. a "remember this choice for this tool" checkbox); its content
+renders at the start of the action row, before Deny/Edit/Approve.
+
+**Exported types:**
+- `ToolApprovalDialogCloseReason = 'escape' | 'backdrop' | 'approve' | 'deny' | 'api' | string` — the
+  `lyra-close` detail; `'escape'`/`'backdrop'`/`'approve'`/`'deny'` come from the dialog's own built-in
+  dismiss triggers, any other string is whatever a caller passes to `close()` directly.
+
+**Properties:**
+- `open: boolean = false` (reflected) — set this (or call `close()`) to dismiss; there is no separate
+  `show()`/`hide()` pair
+- `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
+  `<lyra-json-viewer>` read-only, or stringified into a `<textarea>` while editing
+- `editable: boolean = true` (reflected) — whether an "Edit" affordance is offered at all (assign
+  `false` via a PROPERTY binding, e.g. `.editable=${false}` — a `?editable=${false}`
+  boolean-attribute binding cannot override a true default). When `false`, `args` is always shown
+  read-only and can never be changed before approval.
+
+**Methods:** `close(reason: ToolApprovalDialogCloseReason = 'api'): void` — closes the dialog, emits
+`lyra-close` with `reason`, and returns focus to whatever had it before the dialog opened; a no-op if
+already closed.
+
+**Events:** `lyra-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 `lyra-close` with reason `'approve'`), `lyra-deny` (no detail — `this.emit('lyra-deny')` is
+called with no second argument, so per the DOM spec's `CustomEventInit` default, `event.detail` is
+`null`, not `undefined`; always followed by `lyra-close` with reason `'deny'`), `lyra-close`
+(`detail: ToolApprovalDialogCloseReason` — fired exactly once per dismissal, via Escape, a backdrop
+click, the Approve/Deny buttons, or a `close()` call)
+
+**Slots:** `footer` — optional supplementary content (e.g. a "remember this choice" checkbox),
+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`
+
+**Themeable custom properties:** `--lyra-tool-approval-dialog-overlay-color` (default
+`rgb(0 0 0 / 0.5)` — the backdrop scrim color; component-specific since no shared overlay token
+exists), `--lyra-tool-approval-dialog-mono-font` (default `ui-monospace, SFMono-Regular, Menlo,
+Consolas, monospace` — used by both `tool-name` and the raw-JSON editor), plus shared tokens
+`--lyra-space-xs/-s/-m/-l`, `--lyra-color-surface`, `--lyra-color-border`, `--lyra-radius`,
+`--lyra-shadow`, `--lyra-color-brand`, `--lyra-color-on-brand`, `--lyra-color-danger`,
+`--lyra-color-text`, `--lyra-focus-ring-width/-color/-offset`, `--lyra-opacity-disabled`.
+
+**Optional peer deps:** none — internally renders `<lyra-json-viewer>`, a bundled dependency of this
+package, not an optional peer.
+
+```html
+<lyra-tool-approval-dialog
+  tool-name="send_email"
+  .args=${{ to: 'ops@example.com', subject: 'Deploy finished' }}
+  @lyra-approve=${(e) => runTool(e.detail.args)}
+  @lyra-deny=${() => console.log('denied')}
+  @lyra-close=${(e) => console.log('closed:', e.detail)}
+></lyra-tool-approval-dialog>
+<script type="module">
+  document.querySelector('lyra-tool-approval-dialog').open = true;
+</script>
+```
+
+While `editable`, an Edit button swaps the read-only `<lyra-json-viewer>` for a plain `<textarea>`
+pre-filled with `JSON.stringify(args, null, 2)`. Every keystroke re-validates with `JSON.parse` — the
+Approve button is `disabled` for as long as the current textarea content fails to parse, so a
+malformed edit can never be silently approved as either the broken text or a stale copy of the
+original args. The same button relabels to "Cancel" while editing; clicking it discards the draft
+entirely and returns to the read-only view of the *original* `args` — there is no separate "save"
+step independent of Approve itself. Both `editing` and any in-progress draft reset back to the
+read-only view every time the dialog transitions from closed to open, so a reused instance never
+leaks one proposal's half-finished edit into the next.
+
+Initial focus deliberately does *not* land on Approve: approving a tool call is a consequential,
+potentially irreversible action, so a user who opens the dialog and reflexively presses Enter/Space
+before reading anything should deny, not approve. Deny gets the initial focus instead — the same
+"focus the safe action" convention a native destructive-confirmation dialog typically follows for its
+own Cancel button. Tab/Shift+Tab are bounded to the panel's own focusable content (shadow-piercingly,
+so `<lyra-json-viewer>`'s internal toggle/copy buttons and any slotted custom element's real focusable
+target are found too) via a locally-duplicated focus-trap helper, the same shape `<lyra-dialog>`'s and
+`<lyra-tool-select-dialog>`'s own overlays use.
+
+**Known gotchas:**
+- `editable` defaults to `true` and reflects — see the property note above about overriding it with a
+  property binding, not a boolean-attribute binding.
+- `lyra-deny` has no detail payload: its `event.detail` is `null`, not `undefined`.
+- a consumer flipping `editable` off while an edit is already in progress automatically exits edit mode
+  and discards the draft, so an unreachable "Cancel" affordance is never left stranded on screen.
+- reconnecting the element while still `open` (e.g. a drag-and-drop reparent that keeps the same
+  instance) automatically re-acquires the ref-counted scroll lock and keydown trap it dropped in
+  `disconnectedCallback` — `willUpdate()` alone wouldn't otherwise notice, since disconnect/reconnect
+  fire back-to-back with no update in between.
+- the Approve button's native `disabled` attribute (while the draft is invalid JSON) automatically
+  excludes it from the Tab trap, since the shared `FOCUSABLE_SELECTOR` used to compute the trap's
+  focusable set already skips disabled controls.
+
+---
+
+## `lyra-tool-param-form`
+
+Renders one form control per top-level property of a JSON Schema object, for ad hoc tool invocation or
+approval-editing UIs (e.g. "the agent wants to call `create_event(title, attendees, allDay)` — let the
+user tweak the arguments before running it"). First-party invention (no Web Awesome equivalent).
+
+**Scope limitation (intentional, not accidental):** this component only understands a *flat* object
+schema — every `properties` entry must be `'string'`, `'number'`, `'integer'`, `'boolean'`, or a string
+`enum`. Nested objects, arrays, `oneOf`/`anyOf`/`allOf`, `$ref`, and any other JSON Schema keyword are
+not read. A property whose `type` isn't one of the four above renders a visible "Unsupported field
+type" note instead of silently dropping it or throwing.
+
+**Exported types:**
+- `ToolParamFormPropertyType = 'string' | 'number' | 'integer' | 'boolean'` — the four leaf property
+  types this renderer understands
+- `ToolParamFormProperty { type: ToolParamFormPropertyType; enum?: string[]; description?: string;
+  title?: string; default?: unknown }` — one `schema.properties` entry. `enum` is only meaningful when
+  `type` is `'string'` (rendered as a `<lyra-select>`); `title` is the display label, falling back to
+  the property key itself; `description` renders as helper text under the control; `default` pre-fills
+  a field whenever `value` doesn't already have that key.
+- `ToolParamFormSchema { type: 'object'; properties: Record<string, ToolParamFormProperty>; required?:
+  string[] }` — the (intentionally flat) schema shape this component can render.
+
+**Properties:**
+- `schema: ToolParamFormSchema = { type: 'object', properties: {} }` (attribute: false)
+- `value: Record<string, unknown> = {}` (attribute: false) — exactly what the consumer last set it to.
+  A field with no entry in `value` but a schema `default` *displays* (and is *emitted*, via
+  `lyra-input`) as that default, but the `value` property itself is left alone until the user actually
+  edits that field — mirrors an uncontrolled `<input placeholder>` not writing to `.value`.
+- `name: string = ''` — submission key for optional native `<form>` participation
+- `disabled: boolean = false` (reflected)
+
+**Getters:**
+- `effectiveValue: Record<string, unknown>` — `value` with every property missing from it filled in
+  from `schema`'s own `default`; this is what actually renders and what `lyra-input`'s detail carries.
+  A key the user has explicitly cleared (a real own property set to `undefined`) stays cleared rather
+  than snapping back to its default — only a key genuinely absent from `value` falls back.
+- `errors: Record<string, string>` — the current per-field validation errors (`{ [propertyKey]:
+  message }`), required-and-empty only; independent of which fields have been visited, so it doesn't
+  need a prior `reportValidity()` call to be accurate.
+
+**Methods:**
+- `checkValidity(): boolean` — non-mutating; delegates to the underlying `ElementInternals`, never
+  reveals inline errors.
+- `reportValidity(): boolean` — reveals inline errors for every currently-invalid required field (as
+  if each had been visited) and returns overall validity; the hook a consumer's own Submit/Approve
+  button should call right before acting, mirroring a native `<form>`'s `reportValidity()`.
+
+**Events:** `lyra-input` (`detail: { value: Record<string, unknown> }` — the full current value
+object, every property with defaults resolved, not just the field that changed), `lyra-validity-change`
+(`detail: { valid: boolean; errors: Record<string, string> }` — fired whenever overall validity
+changes, including once up front at connect time, so a consumer sees `valid: false` immediately if a
+required field starts out empty without waiting for user interaction)
+
+**Slots:** none.
+
+**CSS parts:** `base`, `field`, `label`, `description`, `error`
+
+**Themeable custom properties:** no component-specific custom properties; shared tokens only —
+`--lyra-space-l/-xs/-s`, `--lyra-color-border`, `--lyra-radius`, `--lyra-color-surface`,
+`--lyra-color-danger`, `--lyra-color-text-quiet`, `--lyra-focus-ring-width/-color/-offset`,
+`--lyra-opacity-disabled`.
+
+**Optional peer deps:** none — internally renders `<lyra-select>`, `<lyra-option>`, and
+`<lyra-checkbox>`, all bundled dependencies of this package imported directly, not optional peers.
+
+```html
+<lyra-tool-param-form
+  .schema=${{
+    type: 'object',
+    properties: {
+      title: { type: 'string', title: 'Title' },
+      attendees: { type: 'string', enum: ['team', 'everyone'], default: 'team' },
+      allDay: { type: 'boolean', title: 'All day' },
+    },
+    required: ['title'],
+  }}
+  .value=${draftArgs}
+  @lyra-input=${(e) => (draftArgs = e.detail.value)}
+  @lyra-validity-change=${(e) => (formIsValid = e.detail.valid)}
+></lyra-tool-param-form>
+```
+
+This component owns no Submit/Cancel/Approve chrome — a consumer composes it inside their own dialog
+(e.g. `<lyra-tool-approval-dialog>`) and reads `.value`/`.errors`/`checkValidity()` (or calls
+`reportValidity()` right before acting). Fields render in `Object.keys(schema.properties)` order
+(insertion order). A `'string'` property with a non-empty `enum` renders as a `<lyra-select>` of
+`<lyra-option>`s; a plain `'string'` renders a text `<input>`; `'number'`/`'integer'` render a numeric
+`<input type="number">` (`step="1"` for integer, `step="any"` for number); `'boolean'` renders a
+`<lyra-checkbox>` with the field's label projected into its default slot — real slotted content, since
+that's `<lyra-checkbox>`'s documented way to give itself an accessible name, unlike `aria-describedby`
+(neither `<lyra-select>` nor `<lyra-checkbox>` forward a host-level `aria-describedby` to their
+internal focusable element, so for the enum-select case the error message is folded into `aria-label`
+instead, alongside the always-visible adjacent `[part="description"]` text). A `required` boolean
+field means "must be checked" — there is no third "unset" visual state a rendered checkbox can
+represent, so `isFieldEmpty()` treats anything other than `true` as empty for that field's type.
+
+Optional native `<form>` participation is implemented via `ElementInternals` attached directly in the
+constructor (`static formAssociated = true`) rather than a string-value mixin, since this component's
+value is a whole object: `formResetCallback()` clears `value`/touched state back to `{}`, and
+`formDisabledCallback(disabled)` mirrors the wrapping form's disabled state onto the `disabled`
+property. This is a nice-to-have layered on top of the primary `value` + `lyra-input`/
+`lyra-validity-change` contract, not a requirement — a consumer that never puts this inside a `<form>`
+loses nothing.
+
+**Known gotchas:**
+- a schema property whose `type` isn't `'string'`/`'number'`/`'integer'`/`'boolean'` renders an inline
+  "Unsupported field type" message (a plain `.unsupported`-classed element, not one of the documented
+  CSS parts) instead of throwing or being silently dropped.
+- inline per-field errors only render once a field has been visited (`focusout`) at least once, or
+  after an explicit `reportValidity()` call — `checkValidity()` alone never reveals them, matching
+  every other form control in this library (`<lyra-select>`/`<lyra-combobox>`/`<lyra-model-select>`
+  all avoid flashing red before the user has touched anything).
+- `effectiveValue` distinguishes "key absent from `value`" (falls back to `default`) from "key present
+  but `undefined`" (stays cleared) via `hasOwnProperty`, not an `=== undefined` check — relevant if you
+  ever construct `value` objects by hand rather than round-tripping `lyra-input`'s detail.
+- `lyra-validity-change` fires once immediately at connect time even before any user interaction, so a
+  form with an unmet required field announces `valid: false` on mount, not only after the first edit.
+
+---
+
+## `lyra-menu` / `lyra-menu-item`
+
+An anchored dropdown built around a consumer-supplied trigger element (typically an icon button)
+assigned to the `trigger` slot. First-party invention (no Web Awesome equivalent) — a close, drop-
+in-shaped replacement for reaching outside this library for a third-party dropdown to build a gear
+menu, an avatar menu, or a history row's overflow menu. Uses the WAI-ARIA "menu button" pattern —
+`role="menu"`/`role="menuitem"` with real roving DOM focus moving between actual focusable
+`<lyra-menu-item>` rows — deliberately not a `role="listbox"`/`aria-activedescendant` shape (that's
+`<lyra-select>`'s pattern instead).
+
+### `lyra-menu`
+
+**Properties:**
+- `open: boolean = false` (reflected)
+- `placement?: Placement` (reflected — resolved through `rtlAwarePlacement()` (`internal/rtl.ts`),
+  then forwarded to `place()`; defaults to whatever `place()` itself defaults to. A `left`/`right`
+  side is mirrored under `dir="rtl"`, so e.g. `placement="left-start"` still anchors to the menu's
+  trailing edge instead of pinning to the physical left)
+- `label: string = 'Menu'` — accessible name for the `role="menu"` popup; override with something
+  specific (e.g. "Row actions") when a page has more than one menu
+
+**Events:** `lyra-show` (no detail — fires only when `open` transitions to `true`, not for markup
+that renders `open` true from the start), `lyra-hide` (same first-render guard, opposite
+transition), `lyra-menu-select` (`detail: { value }` — a consolidated re-fire of the activated
+`<lyra-menu-item>`'s own `lyra-menu-item-select`; always followed by the menu closing and focus
+returning to the trigger)
+
+**Slots:** `trigger` (the consumer's own trigger element — first assigned element wins if several
+are assigned; enhanced imperatively with `aria-haspopup="menu"`/`aria-expanded`/`aria-controls`
+since those attributes belong on the actual interactive trigger, which lives outside this
+component's shadow root), default (`<lyra-menu-item>` elements, plus optionally plain `<hr>`
+dividers between groups — native `<hr>` already carries an implicit `separator` role)
+
+**CSS parts:** `trigger` (wrapper around the `trigger` slot — the positioning anchor), `popup` (the
+positioned floating panel), `list` (the `role="menu"` container wrapping the default slot)
+
+**Themeable custom properties:** shared tokens only (`--lyra-color-surface`, `--lyra-color-border`,
+`--lyra-radius`, `--lyra-shadow`, `--lyra-space-xs`, `--lyra-transition-fast`).
+
+**Optional peer deps:** none.
+
+### `lyra-menu-item`
+
+Not meaningful standalone — it exists purely as `<lyra-menu>`'s light-DOM child, the same
+relationship `<lyra-option>` has to `<lyra-combobox>`/`<lyra-select>`. `role="menuitem"` and the
+roving `tabindex` both live on the host element itself (mirroring `<lyra-tree-node>`), not an
+internal shadow-DOM button; `<lyra-menu>` is the sole owner of this element's `tabIndex`.
+
+**Properties:**
+- `value: string = ''` — an id/value echoed back in the parent `<lyra-menu>`'s `lyra-menu-select`
+  detail
+- `disabled: boolean = false` (reflected — disables selection and excludes this item from
+  `<lyra-menu>`'s roving-tabindex navigation entirely)
+- `destructive: boolean = false` (reflected — tints the row with `--lyra-color-danger`, for a
+  dangerous action like "Delete")
+
+**Events:** `lyra-menu-item-select` (no detail payload — `this.emit('lyra-menu-item-select')` is
+called with no second argument, so `event.detail` is `null`, not `undefined`; fires on click, or
+when the parent `<lyra-menu>`'s own Enter/Space keydown handling calls `select()` on the currently
+roving-focused item)
+
+**Slots:** default (the item's label content), `icon` (optional leading icon)
+
+**CSS parts:** `base` (the row — `role` lives on the host, not this part), `icon` (wrapper around
+the `icon` slot; not rendered/hidden entirely while the slot is empty), `label` (wrapper around the
+default slot)
+
+**Themeable custom properties:** shared tokens only (`--lyra-radius`, `--lyra-focus-ring-width`,
+`--lyra-focus-ring-color`, `--lyra-space-xs`, `--lyra-space-s`, `--lyra-color-brand-quiet`,
+`--lyra-opacity-disabled`, `--lyra-color-danger`, `--lyra-color-danger-quiet`).
+
+**Optional peer deps:** none.
+
+```html
+<lyra-menu label="Row actions">
+  <button slot="trigger" aria-label="More actions">⋮</button>
+  <lyra-menu-item value="edit">Edit</lyra-menu-item>
+  <lyra-menu-item value="duplicate">Duplicate</lyra-menu-item>
+  <hr />
+  <lyra-menu-item value="delete" destructive>Delete</lyra-menu-item>
+</lyra-menu>
+<script type="module">
+  document.querySelector('lyra-menu').addEventListener('lyra-menu-select', (e) => console.log(e.detail.value));
+</script>
+```
+
+The popup is always rendered in the DOM (never `display:none`) so `.focus()` calls on its content
+work synchronously the instant it opens — closed state is conveyed via `visibility`/`opacity`
+instead. `visibility` is an inherited CSS property that pierces the `<slot>` projection boundary, so
+every closed-state `<lyra-menu-item>` is automatically excluded from sequential (Tab-key)
+navigation with no separate JS bookkeeping. Once open, ArrowDown/ArrowUp move the roving focus among
+non-disabled items and wrap past either end; Home/End jump to the first/last non-disabled item;
+Enter/Space activate the focused item; Escape closes and refocuses the trigger. A click outside both
+the trigger and the open popup also closes it, but deliberately does *not* refocus the trigger — the
+outside click itself already moved focus somewhere the user chose.
+
+**Known gotchas:**
+- `<lyra-menu-item>`'s click handler lives on an inner shadow-DOM element (`[part="base"]`), not the
+  host — calling `.click()` directly on the `<lyra-menu-item>` host element in a test does **not**
+  trigger selection; you must click (or dispatch on) the element returned by
+  `menuItemEl.shadowRoot.querySelector('[part="base"]')`.
+- `lyra-show`/`lyra-hide` are suppressed on the very first render even if `open` is already `true`
+  in markup — only later `open` transitions fire them.
+- `lyra-menu-item-select` carries no detail payload (`event.detail === null`); read
+  `event.target.value` instead. `<lyra-menu>`'s own re-fired `lyra-menu-select` is the one that
+  carries `detail: { value }`.
+- Tab closes the menu without `preventDefault()` or focus trapping — the browser's own default Tab
+  navigation proceeds untouched, only the (now-stale) open state is cleared.
+- Only Escape and a committed selection refocus the trigger on close; a click outside does not.
+
+---
+
+## `lyra-chip` / `lyra-chip-group`
+
+A small, content-agnostic pill for a short label: a tag, an active-filter/scope indicator, etc.
+Distinct from `<lyra-attachment-chip>` (specifically file-shaped, with a thumbnail/size/upload-
+progress) — this pair carries no domain assumptions at all. `<lyra-chip>` is a controlled component:
+clicking its remove (×) button only fires `lyra-remove` — the chip never removes itself from the DOM
+on its own interaction, the same contract `<lyra-attachment-chip>`/`<lyra-conversation-item>`
+already follow.
+
+### `lyra-chip`
+
+**Properties:**
+- `tone: 'neutral' | 'brand' | 'success' | 'warning' | 'danger' = 'neutral'` (reflected — tints the
+  whole pill using a loud-color-on-quiet-tint convention; `neutral` has no dedicated token pair, so
+  it falls back to a plain bordered-surface look)
+- `removable: boolean = false` (reflected — shows the remove (×) button)
+- `value?: string` — opaque consumer bookkeeping value, never read, validated, or rendered by this
+  component itself, only ever echoed back verbatim (including `undefined` if never set) in
+  `lyra-remove`'s detail
+
+**Events:** `lyra-remove` (`detail: { value }` — the remove (×) button was activated via click or
+Enter/Space while focused; only rendered/reachable while `removable`)
+
+**Slots:** default (the chip's label content), `icon` (optional leading icon or status dot; nothing
+reserved for it — no extra gap — when left empty)
+
+**CSS parts:** `base` (the pill's root container), `icon` (wrapper around the `icon` slot; hidden
+entirely while empty), `label` (wrapper around the default slot), `remove-button` (the remove (×)
+affordance, only rendered while `removable`)
+
+**Themeable custom properties:** `--lyra-chip-accent`, `--lyra-chip-bg`, `--lyra-chip-border`
+(component-local trio swapped per `tone` rather than repeating background/color/border per part per
+tone; default `var(--lyra-color-text)` / `var(--lyra-color-surface)` / `var(--lyra-color-border)` —
+mirrors the same accent/bg/border vocabulary `<lyra-tool-call-chip>`/`<lyra-attachment-chip>` use),
+plus shared tokens (`--lyra-space-xs`, `--lyra-space-s`, `--lyra-color-brand`/`-brand-quiet`,
+`--lyra-color-success`/`-success-quiet`, `--lyra-color-warning`/`-warning-quiet`,
+`--lyra-color-danger`/`-danger-quiet`, `--lyra-icon-button-size`, `--lyra-focus-ring-width`,
+`--lyra-focus-ring-color`, `--lyra-focus-ring-offset`, `--lyra-transition-fast`).
+
+**Optional peer deps:** none.
+
+### `lyra-chip-group`
+
+A flex-wrap container for a set of `<lyra-chip>` children — plain light-DOM composition, direct
+children are the chips (the same shape `<lyra-split>`'s panels / `<lyra-source-list>`'s cards take,
+no `.items` array prop).
+
+**Properties:**
+- `maxVisible?: number` (attribute `max-visible`) — maximum number of direct children shown before
+  the rest collapse behind a "+N" indicator; unset (the default) means no limit, every child is
+  always shown
+
+**Events:** `lyra-overflow-toggle` (`detail: { expanded }` — the overflow indicator was activated,
+revealing or re-collapsing the excess children; fires only from that click, i.e. only when
+`max-visible` is actually causing an overflow state — never as a side effect of `max-visible`/
+children changing on their own)
+
+**Slots:** default (`<lyra-chip>` elements, or any content, though the chip pairing is the intended
+usage)
+
+**CSS parts:** `base` (the flex-wrap container, holds both the slot and the overflow indicator),
+`overflow-indicator` (the "+N" / "Show less" toggle button; only rendered while `max-visible` is
+actively causing an overflow — a locally-styled pill, not an instantiated real `<lyra-chip>`)
+
+**Themeable custom properties:** shared tokens only (`--lyra-space-xs`, `--lyra-space-s`,
+`--lyra-color-border`, `--lyra-color-surface`, `--lyra-color-text-quiet`, `--lyra-color-text`,
+`--lyra-color-brand`, `--lyra-focus-ring-width`, `--lyra-focus-ring-color`,
+`--lyra-focus-ring-offset`, `--lyra-transition-fast`).
+
+**Optional peer deps:** none.
+
+```html
+<lyra-chip-group max-visible="3">
+  <lyra-chip removable value="draft">Draft</lyra-chip>
+  <lyra-chip tone="success" removable value="reviewed">Reviewed</lyra-chip>
+  <lyra-chip tone="warning">Needs input</lyra-chip>
+  <lyra-chip tone="danger">Blocked</lyra-chip>
+</lyra-chip-group>
+<script type="module">
+  const group = document.querySelector('lyra-chip-group');
+  group.addEventListener('lyra-overflow-toggle', (e) => console.log(e.detail.expanded));
+  group.querySelectorAll('lyra-chip').forEach((chip) => chip.addEventListener('lyra-remove', (e) => console.log(e.detail.value)));
+</script>
+```
+
+Since CSS alone can't parameterize `:nth-child` on a runtime prop, `<lyra-chip-group>` reaches
+directly into the light DOM and sets each excess child's own `hidden` property once `max-visible` is
+exceeded — the same approach `<lyra-split>` uses to set each panel's inline `flex`/`order`, rather
+than a stylesheet-only solution.
+
+**Known gotchas:**
+- `<lyra-chip>`'s accessible remove-button label ("Remove {text}") is computed only from the default
+  slot's own text content — text living inside the (decorative) `icon` slot doesn't leak into it.
+- `<lyra-chip-group>` silently un-expands (`expanded` resets to `false`, with no event firing) if a
+  consumer raises `max-visible` past the current child count while already expanded — only an actual
+  click on the overflow indicator fires `lyra-overflow-toggle`.
+- `<lyra-chip-group>`'s overflow indicator is its own locally-styled pill, not an instantiated
+  `<lyra-chip>` in its shadow DOM — don't expect `<lyra-chip>`'s CSS parts or custom properties to
+  reach it.
+
+---
+
+## `lyra-model-settings-panel`
+
+A fixed composition of `<lyra-model-select>` and `<lyra-slider>` into one agent-configuration card:
+pick a provider's model, then tune its sampling temperature. First-party invention (no Web Awesome
+equivalent). Not a generic layout shell — it exists so a consumer doesn't have to re-wire the same
+two child `lyra-change` events into one combined settings object by hand every time this pairing
+comes up.
+
+Every prop here is a plain pass-through to (or mirror of) the matching child control's own prop of
+the same/similar name — see `lyra-model-select` and `lyra-slider` themselves for the exact semantics
+of `catalog`/`allowCustom` and `temperatureMin`/`temperatureMax`/`temperatureStep`.
+
+**Properties:**
+- `provider: string = ''` — informational provider badge, passed straight through to the internal
+  `lyra-model-select`.
+- `catalog?: LyraModelCatalog` (attribute: false, JS-only) — `string[] | { id: string; label: string
+  }[]` (every entry must be one shape or the other, never mixed); passed straight through to the
+  internal `lyra-model-select`.
+- `modelValue: string = ''` (attribute `model-value`) — the current model id.
+- `allowCustom: boolean = false` (attribute `allow-custom`) — lets the model control accept a value
+  outside `catalog`; passed straight through.
+- `temperature: number = 1` — the current sampling temperature. `1` is the midpoint of the default
+  `[0, 2]` range and matches both OpenAI's and Anthropic's own provider default; reassign it yourself
+  if your provider differs.
+- `temperatureMin: number = 0` (attribute `temperature-min`)
+- `temperatureMax: number = 2` (attribute `temperature-max`)
+- `temperatureStep: number = 0.1` (attribute `temperature-step`)
+- `layout: 'vertical' | 'compact' = 'vertical'` (reflected) — `vertical` stacks full-width rows with
+  visible labels; `compact` runs the same two rows side by side with a smaller, uppercase temperature
+  caption, for toolbars/sidebars where the vertical layout's height doesn't fit.
+
+**Events:** `lyra-change` — `detail: { modelValue: string; inCatalog: boolean; temperature: number }`.
+Fires whenever *either* child control's own `lyra-change` fires, and always carries the full current
+settings snapshot, not just whichever field actually changed. `inCatalog` is recomputed fresh from
+`catalog`/`modelValue` on every emission (mirroring `lyra-model-select`'s own `effectiveEntries` logic)
+rather than cached from the last child event, so it's still correct even when `modelValue` was just
+assigned directly instead of via the child's own event.
+
+**Slots:** none — this is a fixed two-control composition, not a generic layout shell.
+
+**CSS parts:** `base`, `model-row`, `temperature-row`, `temperature-label`, `temperature-value`
+
+**Themeable custom properties:** no component-specific custom properties; consumes shared tokens
+`--lyra-space-l/-m/-s/-xs`, `--lyra-color-border`, `--lyra-radius`, `--lyra-color-surface`,
+`--lyra-color-text`, `--lyra-color-text-quiet`.
+
+**Optional peer deps:** none — it composes the library's own `<lyra-model-select>` and `<lyra-slider>`
+internally (both imported unconditionally as side effects, not optional).
+
+```html
+<lyra-model-settings-panel
+  provider="OpenAI"
+  .catalog=${['gpt-4o', 'gpt-4o-mini', 'gpt-4.1']}
+  model-value="gpt-4o"
+  temperature="0.7"
+  @lyra-change=${(e) => console.log(e.detail)}
+></lyra-model-settings-panel>
+
+<lyra-model-settings-panel layout="compact" .catalog=${catalog}></lyra-model-settings-panel>
+```
+
+The internal `lyra-slider` renders with its own value readout suppressed (`.showValue=${false}`);
+the current temperature is instead shown via this component's own `[part="temperature-value"]` span,
+which interpolates `temperature` verbatim with no `toFixed`/formatting applied — a value like `0.1`
+shows as `0.1`, and any floating-point noise a slider drag produces would render digit-for-digit.
+
+**Known gotchas:**
+- `catalog` is JS-only (`attribute: false`) — set it via a property binding (`.catalog=`), never as
+  an HTML attribute, same requirement as the underlying `lyra-model-select`.
+- `layout="compact"` removes the host's own `max-inline-size` cap (`28rem` in `vertical` layout)
+  entirely, so a compact panel can grow as wide as its container/flex context allows.
+- The nested `lyra-model-select`'s own `max-inline-size` (sized for a standalone dropdown) is
+  overridden to `100%`/`none` inside `[part="model-row"]` so it fills the card's full width — a
+  detail only worth knowing if you're targeting `lyra-model-select` internals with your own CSS
+  through this component.
+
+---
+
+## `lyra-context-meter`
+
+A segmented occupancy meter (bar or ring) for showing how a fixed capacity — a model's context
+window, a token budget, any consumable quota — is divided across labeled categories. First-party
+invention (no Web Awesome equivalent). Pure data visualization: it renders `segments`/`total` exactly
+as given and never computes token counts, costs, or any other domain-specific estimate itself — the
+one exception is the plain arithmetic sum of segment values used to build the accessible "X of Y
+used" summary.
+
+**Properties:**
+- `segments: ContextMeterSegment[] = []` (attribute: false, JS-only) — `{ label: string; value:
+  number; tone?: 'brand' | 'success' | 'warning' | 'danger' | 'neutral' }[]`. `value` is an *absolute*
+  quantity measured against `total`, never a pre-computed percentage.
+- `total: number = 0` — the full capacity segments are measured against (e.g. a model's context
+  window size).
+- `variant: 'ring' | 'bar' = 'bar'` (reflected)
+- `label: string = ''` — overall accessible caption, e.g. `"128K context window"`. Also rendered
+  visually (`[part="label"]`) when set.
+
+**Events:** none.
+
+**Slots:** none.
+
+**CSS parts:** `base` (a `<div>` for `bar`, an `<svg>` for `ring`), `track` (the unfilled/empty
+capacity), `segment` (one occupied segment — carries `data-tone` for styling), `label`
+
+**Themeable custom properties:** no component-specific custom properties; consumes shared tokens
+`--lyra-space-xs`, `--lyra-color-text-quiet`, `--lyra-font`, `--lyra-radius`, `--lyra-color-border`,
+`--lyra-color-brand`, `--lyra-color-success`, `--lyra-color-warning`, `--lyra-color-danger`,
+`--lyra-transition-base`.
+
+**Optional peer deps:** none.
+
+```html
+<lyra-context-meter
+  label="128K context window"
+  total="128000"
+  .segments=${[
+    { label: 'System prompt', value: 2200, tone: 'neutral' },
+    { label: 'Conversation history', value: 61000, tone: 'brand' },
+    { label: 'Retrieved context', value: 30800, tone: 'warning' },
+  ]}
+></lyra-context-meter>
+
+<lyra-context-meter variant="ring" total="128000" .segments=${segments}></lyra-context-meter>
+```
+
+`role="img"` and a computed `aria-label` are set imperatively on the *host* element itself in
+`willUpdate` (mirroring `lyra-gauge`'s "meter" role convention) — every internal node (`track`,
+`segment`, the ring's `<svg>`, `label`) is `aria-hidden`, so a screen reader gets one meaningful
+summary string instead of the raw markup. That summary's "used" figure is the plain, unclamped sum of
+`segments[].value` (`"150,000 of 128,000 used"` is possible if segments overshoot `total`), even
+though the *visual* meter itself never overflows: each segment's ratio is clamped so the running
+cumulative fill across all segments can never exceed 100% of the bar/ring — an over-`total` `segments`
+array renders as a fully (not over-) filled meter, with later segments truncated or squeezed to zero
+width/arc-length as the budget runs out. `total <= 0` (or non-finite) renders zero segments — an empty
+track/ring — regardless of what's in `segments`. Ring geometry (a 40-radius circle, 12px stroke,
+centered at 50,50) intentionally matches `lyra-gauge`'s own radial numbers, so the two circular-meter
+components in the library share one visual scale.
+
+**Known gotchas:**
+- The ring variant's per-segment `<title>` and the bar variant's per-segment `title=` attribute are
+  native mouse-hover tooltips only — they sit inside `aria-hidden` markup, so screen readers never
+  read them; only the host's own `role="img"`/`aria-label` carries accessible information.
+- `variant="ring"` fixes the host at `8em × 8em` (`:host([variant='ring'])`) — the bar variant's
+  `inline-size: 100%` does not apply in ring mode; resize it via `font-size` or an explicit
+  width/height override on the host instead.
+- Segment order is significant for the ring's cumulative `stroke-dashoffset` — later entries in
+  `segments` render further around the circle (starting at 12 o'clock, going clockwise); there's no
+  independent sort/z-order control.
+
+---
+
+## `lyra-dock-panel`
+
+A single panel docked to one edge of whatever contains it, resizable by dragging its inner edge.
+First-party invention (no Web Awesome equivalent). Unlike `lyra-split` (which owns and lays out N
+sibling panels, and requires restructuring a layout so every panel becomes its direct child), this is
+one self-contained element you drop next to your existing content — typically as an absolutely-
+positioned child of a `position: relative` parent, or as a flex item alongside a main-content sibling.
+It deliberately imposes no `position`/`inset` of its own: it only manages its own size along the
+resize axis (`inline-size` for `start`/`end`, `block-size` for `top`/`bottom`) and fills 100% of the
+cross axis, leaving where it sits in the page entirely up to the consumer's own layout. `lyra-split`
+stays the right primitive for the multi-sibling-panel case; this is the primitive for the single-edge-
+docked case.
+
+**Properties:**
+- `edge: 'start' | 'end' | 'top' | 'bottom' = 'end'` (reflected) — which edge of the panel's own
+  container it's docked to. `start`/`end` are logical-inline (mirror left/right depending on writing
+  direction); `top`/`bottom` are block-direction and unaffected by RTL.
+- `size: string = '280px'` — the current docked size along the resize axis, as a CSS length.
+- `minSize: string = '160px'` (attribute `min-size`) — minimum resize bound, as a CSS length.
+- `maxSize: string = ''` (attribute `max-size`) — maximum resize bound. Empty means "no explicit
+  cap": the live extent of the containing element is used instead (falling back to the viewport if
+  there's no parent, e.g. not yet connected), so the panel still can't be dragged wider/taller than
+  its container.
+- `collapsible: boolean = false` (reflected)
+- `collapsed: boolean = false` (reflected)
+- `resizable: boolean = true` (reflected) — when `false`, no drag handle renders at all and the panel
+  is a fixed size. (Assign `false` via a **property** binding, e.g. `.resizable=${false}` — a
+  `?resizable=${false}` boolean-attribute binding cannot override a `true` default; see AGENTS.md.)
+
+**Exported helper:** `parseLengthPx(length: string, containerPx: number, fontSizeEl: Element =
+document.documentElement): number | undefined` — resolves an arbitrary CSS length (`px`, `rem`, `em`,
+`vw`, `vh`, `%`, or a bare/unitless number treated as `px`) to a live pixel value without a DOM-probe
+measurement, since `min-size`/`max-size` are pure constraints that are never themselves rendered
+anywhere. `rem` resolves against the document root's font size; `em` resolves against `fontSizeEl`'s
+own computed font size; `%` resolves against `containerPx`. Returns `undefined` for an
+empty/unparseable string. Used internally to resolve `min-size`/`max-size`; the panel's *current* size
+is instead always read back live from `getBoundingClientRect()`, which handles any unit for free.
+
+**Events:**
+- `lyra-resize` — `detail: { size }` (a `px` CSS length string), fired on every drag step, drag
+  release, and keyboard step.
+- `lyra-collapse-change` — `detail: { collapsed }`, fired whenever the collapse toggle flips
+  `collapsed`.
+
+**Slots:** default — the panel's own content.
+
+**CSS parts:** `base` (the panel root), `content` (wraps the default slot; hidden while `collapsed`),
+`handle` (the draggable resize edge; only rendered when `resizable` and not `collapsed`),
+`collapse-toggle` (only rendered when `collapsible`)
+
+**Themeable custom properties:** `--lyra-dock-panel-collapsed-size` (default
+`var(--lyra-icon-button-size)`) — the persistent "rail" width/height the panel holds at while
+`collapsed`, rather than collapsing to zero (a zero-size collapsed panel would have nowhere to host
+the re-expand toggle); component-specific since collapse never zeroes the box. Plus shared tokens
+`--lyra-color-surface`, `--lyra-color-border`, `--lyra-color-brand`, `--lyra-color-brand-quiet`,
+`--lyra-color-text`, `--lyra-radius`, `--lyra-space-xs`, `--lyra-focus-ring-width/-color/-offset`,
+`--lyra-transition-fast`, `--lyra-icon-button-size`.
+
+**Optional peer deps:** none.
+
+```html
+<div style="position: relative; block-size: 100vh;">
+  <lyra-dock-panel
+    edge="end"
+    size="320px"
+    min-size="200px"
+    max-size="480px"
+    collapsible
+    @lyra-resize=${(e) => console.log(e.detail.size)}
+    @lyra-collapse-change=${(e) => console.log(e.detail.collapsed)}
+  >
+    <div>Sidebar content — a chat thread list, an inspector, anything.</div>
+  </lyra-dock-panel>
+</div>
+```
+
+Pointer-drag-resize mirrors `lyra-split`'s pointer-capture technique (`pointerdown` captures the
+pointer on the handle; `pointermove` computes a new size; `pointerup`/`pointercancel`/
+`lostpointercapture` all release it, since a drag can end without a clean `pointerup`) but reasons in
+raw pixels throughout rather than percent. Every resize — drag step, drag release, or a keyboard step
+(<kbd>ArrowLeft</kbd>/<kbd>ArrowRight</kbd> for the inline axis, <kbd>ArrowUp</kbd>/<kbd>ArrowDown</kbd>
+for the block axis, 16px per step) — always commits `size` as a rounded `px` string regardless of
+what unit `size`/`min-size`/`max-size` were originally expressed in.
+
+**Known gotchas:**
+- `collapsed` doesn't zero the panel's box — it shrinks to the persistent rail size
+  (`--lyra-dock-panel-collapsed-size`). `size` itself is left untouched while collapsed, so
+  re-expanding restores exactly what it was.
+- `handle` only renders while `resizable && !collapsed`; `collapse-toggle` only renders while
+  `collapsible` — a panel with both `false` renders neither control, just fixed-size slotted content.
+  `resizable` and `collapsed` interact: dragging is disabled whenever `collapsed` is `true`, even if
+  `resizable` is also `true`.
+- The collapse-toggle's chevron rotates to point toward the panel's pinned edge when expanded (the
+  direction clicking it will shrink toward) and away from it when collapsed — this is folded through
+  both `edge` and, for `start`/`end`, current RTL-ness, so the same markup visually flips correctly
+  under `dir="rtl"` with no extra author work.
+
+---
+
+## `lyra-document-preview`
+
+A format-dispatching viewer for one document/attachment, plus the visual state machine for an async
+server-side conversion a host app runs in front of it. First-party invention (no Web Awesome
+equivalent).
+
+Format dispatch is intentionally minimal: only `text/*`/`application/json` (a plain, scrollable
+`<pre>` — no syntax highlighting; compose `<lyra-code-block>` yourself via the `unsupported` slot for
+that) and `image/*` (a contained `<img>`) render inline. Everything else — PDF, office documents,
+video, audio, or any unrecognized MIME type — falls back to a generic "can't preview this" state: a
+file glyph, a short message, and (when `src` is set) a native `<a download>` link. This is a
+deliberate ceiling, not a gap: the component ships a dispatch *shell*, not a format registry. The
+`unsupported` slot is the escape hatch for every format left out of the built-in three.
+
+`status="converting"` is a second, independent axis from format dispatch. This component doesn't know
+your backend's conversion API shape and owns none of the actual polling/fetch — a host converting a
+non-natively-previewable format server-side (e.g. `.docx` → `.pdf`) polls its own backend and updates
+`status`/`progress`/`src` here as that proceeds; this component only *visualizes* that state (an
+indeterminate spinner, or a determinate one once `progress` is supplied). The one piece of async work
+this component *does* own is fetching a `text/*`/`application/json` `src` itself — there's no other
+way to get a `<pre>`'s text content from a URL — gated behind a generation-counter guard
+(`lyra-tool-result-view`'s `resolve()` uses the identical pattern) so a `src` reassigned mid-fetch
+can't have a stale response clobber a newer one.
+
+**Properties:**
+- `src: string = ''` — URL to fetch (for `text`/`application/json`) or display (`image`, or as the
+  generic fallback's download `href`). Optional — gracefully absent while, e.g., a conversion is
+  still in progress.
+- `mimeType: string = ''` (attribute `mime-type`) — drives format dispatch (see above).
+- `filename: string = ''` — shown in the header and used as the download link's suggested filename.
+- `status: 'idle' | 'converting' | 'ready' | 'error' = 'idle'` (reflected) — host-owned lifecycle
+  state. `"converting"` shows the spinner regardless of `mimeType`/`src`; `"error"` shows
+  `errorMessage` regardless of either. `"idle"`/`"ready"` both resume normal format dispatch — a host
+  with no conversion step never has to explicitly set `"ready"`.
+- `progress?: number` (type `Number`) — 0-100. Only consulted while `status="converting"`. Unset (the
+  default) renders an indeterminate spinner instead of a determinate progress bar.
+- `errorMessage: string = ''` (attribute `error-message`) — shown via `[part="error"]` while
+  `status="error"`.
+- `maxHeight: string = ''` (attribute `max-height`) — a CSS length (e.g. `"24rem"`); once set,
+  `[part="body"]` scrolls internally past this height instead of growing the page — same contract as
+  `lyra-json-viewer`'s identically-named prop.
+
+**Events:**
+- `lyra-download` — `detail: { src, filename }` — fired when the generic-download fallback's link is
+  activated. The browser download itself needs no JS (a plain `<a download>` handles it); this is
+  purely for a host that wants to observe/log the download.
+- `lyra-render-error` — `detail: { error }` — fired when this component's own `text/*`/
+  `application/json` `fetch(src)` fails (network error or non-2xx response). Distinct from
+  `status="error"`, which is entirely host-driven.
+
+**Slots:** `unsupported` — escape hatch: when populated, its content renders *instead of* the generic
+download fallback for any `mime-type` this component doesn't natively support. Ignored while
+`mime-type` resolves to `text`/`image` dispatch, or while `status` is `"converting"`/`"error"`.
+
+**CSS parts:** `base`, `header` (hidden entirely when `filename` is unset), `filename`, `body`,
+`spinner` (indeterminate `role="status"`, or `role="progressbar"` once numeric progress is known —
+used both for `status="converting"` and this component's own in-flight text fetch), `error`
+(`role="alert"` — used both for `status="error"` and a failed text fetch), `download-link` (only
+rendered when `src` is set)
+
+**Themeable custom properties:** `--lyra-document-preview-max-height` (default `none`) — the
+consumer-tunable scroll cap on `[part="body"]`, set from `max-height`; `none` means the preview grows
+with its content until a caller opts in. `--lyra-document-preview-font` (default `ui-monospace,
+SFMono-Regular, Menlo, Consolas, monospace`) — no shared `--wa-*`/`--lyra-*` monospace token exists yet
+(the same gap `lyra-json-viewer`'s own `--lyra-json-viewer-font` documents). Plus shared tokens
+`--lyra-color-border`, `--lyra-radius`, `--lyra-color-surface`, `--lyra-space-s/-m/-l/-xs`,
+`--lyra-color-text`, `--lyra-color-text-quiet`, `--lyra-color-danger`, `--lyra-color-brand`,
+`--lyra-color-on-brand`, `--lyra-focus-ring-width/-color/-offset`, `--lyra-transition-fast`.
+
+**Optional peer deps:** none directly — the `unsupported` slot is commonly used to compose
+`<lyra-code-block>` (which has its own optional `shiki` peer dependency; see that component's own
+entry) or a third-party PDF/office-doc viewer, but neither is a dependency of this component itself.
+
+```html
+<lyra-document-preview
+  filename="board-notes.txt"
+  mime-type="text/plain"
+  src="/files/board-notes.txt"
+  max-height="24rem"
+  @lyra-render-error=${(e) => console.error(e.detail.error)}
+></lyra-document-preview>
+
+<!-- A host driving its own server-side conversion -->
+<lyra-document-preview filename="deck.pptx" status="converting" progress="42"></lyra-document-preview>
+
+<!-- Escape hatch for an unsupported format -->
+<lyra-document-preview filename="deck.pptx" mime-type="application/vnd.ms-powerpoint" src="/files/deck.pptx">
+  <lyra-code-block slot="unsupported" language="text">Open in PowerPoint to preview.</lyra-code-block>
+</lyra-document-preview>
+```
+
+Accessibility: the `"converting"` state without numeric `progress` is a `role="status"` region
+wrapping a visually-hidden "Converting document…" string — a *plain* static region, not routed
+through `<lyra-live-region>`/`Announcer`, since (like `<lyra-typing-indicator>`) it only ever has one
+thing to announce (entering the state), not a rapidly-repeating stream. Once real `progress` is
+available, the region becomes a standard `role="progressbar"` instead, self-describing via
+`aria-valuenow` with no extra live-region wiring. `status="error"` renders `[part="error"]` as
+`role="alert"` — a one-shot assertive notice, without needing the announcer machinery either.
+
+**Known gotchas:**
+- `status="converting"`/`status="error"` always win over format dispatch, regardless of
+  `mimeType`/`src` — a `text`/`image` source is not shown until `status` returns to `"idle"`/`"ready"`.
+- The component's own text/JSON `fetch(src)` is a *different* async operation from the host-driven
+  `status="converting"` conversion. A failed fetch fires `lyra-render-error` and renders
+  `[part="error"]` on its own; it never sets `status="error"` itself.
+- `progress` is only ever consulted for the host-driven `"converting"` state — this component's own
+  in-flight text fetch always renders the indeterminate spinner, with no numeric-progress path.
+- The `unsupported` slot's initial presence is detected once, before the first render, by scanning
+  light-DOM children directly (not the slot's `assignedElements()`); every later slot-content change
+  is instead picked up via the slot's own `slotchange` listener. Both paths keep detection correct,
+  just via two different mechanisms depending on timing.
+- `download-link` (and thus `lyra-download`) only renders/fires when `src` is set — a generic-fallback
+  state with no `src` shows only the file glyph and message, with no download affordance at all.
+
+---
+
+## `lyra-media-card`
+
+A lightweight inline preview for one already-sent, already-available attachment inside a rendered
+chat message body — distinct from `lyra-document-preview` (a fuller viewer with an async
+server-side-conversion state machine) and `lyra-attachment-chip` (a pre-send queued-file chip with
+upload progress). This component has neither concern; it only ever shows a `src` that's already
+final.
+
+**Properties:**
+- `src: string = ''` — the media URL. Always re-validated against a safe-scheme allowlist before
+  use (see below) — never trust it unsanitized even though it's typed as a plain string.
+- `kind?: 'image' | 'video' | 'file'` (reflected) — explicit format dispatch. Leave unset to
+  auto-detect from `mimeType`.
+- `mimeType: string = ''` (attribute `mime-type`) — drives auto-detection when `kind` is unset.
+- `filename: string = ''` — shown in the file-chip fallback, used as the download link's suggested
+  filename, and folded into the accessible name.
+- `alt: string = ''` — alt text for the image case (and reused as a video label fallback). Falls
+  back to `filename`, then a generic per-kind description.
+
+**Events:** `lyra-open` (`detail: { src: string; filename: string }`, cancelable) — fired when the
+card (or, for `kind="video"`, its separate `open-button`) is activated. This component never
+navigates on its own for `image`/`video` — a host decides what "open" means. The `file`-chip case is
+the exception: when `src` passes the stricter href safety check, the chip is a real `<a href
+download>` so a bare drop-in still does something useful, but `lyra-open` fires first — a host
+calling `preventDefault()` on it suppresses that default download/open so it can substitute its own
+handling.
+
+**Slots:** none.
+
+**CSS parts:** `base` (a `<button>` for `kind="image"`, a plain wrapper `<div>` for `kind="video"`,
+an `<a>` or `<span>` for the file-chip fallback depending on href safety), `media` (the `<img>`/
+`<video>`), `file-icon`, `filename` (file-chip fallback only), `open-button` (video only — see
+below).
+
+**Themeable custom properties:** shared tokens only — `--lyra-space-xs`/`-s`, `--lyra-color-border`,
+`--lyra-color-surface`, `--lyra-color-text`/`-text-quiet`, `--lyra-radius`, `--lyra-focus-ring-*`.
+
+**Optional peer deps:** none.
+
+```html
+<lyra-media-card kind="image" src="https://example.com/photo.jpg" alt="Screenshot" filename="photo.jpg"
+  @lyra-open=${(e) => openLightbox(e.detail.src)}
+></lyra-media-card>
+<lyra-media-card kind="file" src="https://example.com/report.pdf" filename="report.pdf"></lyra-media-card>
+```
+
+**Safe-URL checking.** `src` is validated (exported as `safeMediaSrc()`/`safeLinkHref()`) before it's
+ever assigned to an `<img>`/`<video>` `src` or an `<a href>` — only `http:`/`https:`/`blob:` (plus
+`data:` for a *media* `src` only) or a scheme-relative/relative URL with no scheme at all pass;
+anything else (`javascript:`, `vbscript:`, and similarly suspicious schemes) is rejected. `data:` is
+allowed for `safeMediaSrc()` (a browser never executes script from a media element's `src`) but
+rejected by the stricter `safeLinkHref()` (a `data:text/html` URI navigated to via a clicked `<a
+href>` runs as a full document and can execute script) — the same scheme gets a different verdict
+depending on which DOM sink it's headed for. Both functions delegate to the platform's own `new
+URL()` parser rather than a hand-rolled scheme regex, specifically because `new URL()` already
+implements the WHATWG URL Standard's input normalization (stripping tab/newline/leading-trailing
+space before looking for a scheme) — a naive regex is vulnerable to exactly the kind of
+tab-injected-into-a-scheme bypass a browser attribute sink still normalizes and executes. An
+`image`/`video` `kind` whose `src` fails the media-src check falls back to the generic file-chip
+rendering, which then separately re-validates `src` against the stricter href allowlist for its own
+download affordance.
+
+`kind="video"` renders its open affordance as a separate `[part="open-button"]` next to
+`[part="media"]` rather than wrapping the whole card in one `<button>`/`<a>` (the pattern
+`image`/`file` use) — a `<video controls>` element is itself interactive content, and HTML forbids
+nesting interactive content inside a `<button>`/`<a>`; doing so anyway would also make every click on
+the video's own native controls bubble up and spuriously fire `lyra-open`.
+
+**Known gotchas:**
+- Calling the real `.click()` (or dispatching a `click`/`MouseEvent`) on the file-chip's `<a href>`
+  in a test genuinely triggers real browser navigation — always `preventDefault()` on a `click`
+  listener registered before triggering it, the same precaution `lyra-document-preview`'s own
+  download-link tests already take. A synthetic `dispatchEvent(new MouseEvent('click', {cancelable:
+  true}))` still invokes the anchor's native activation behavior if nothing calls
+  `preventDefault()` during dispatch — it is not a safe no-op.
+- `kind` only reflects to the host attribute when explicitly set — CSS keying off the
+  auto-detected resolved kind should target the rendered `[part]`/element (e.g. `video[part="media"]`),
+  not `:host([kind=...])`, since the latter won't see an auto-detected kind.
+
+---
+
+## `lyra-attachment-trigger`
+
+A compact attach affordance designed for a chat composer's leading slot (see `lyra-chat-composer`'s
+own `leading` slot, which this drops straight into, though it has no code dependency on it). First-
+party invention (no Web Awesome equivalent). Its shape adapts to how many attachment `capabilities`
+are configured: exactly one renders a single plain icon button; more than one renders a small
+anchored menu (composed from the already-landed `lyra-menu`/`lyra-menu-item`) listing each
+capability as a row.
+
+**Properties:**
+- `capabilities: AttachmentCapability[] = ['files']` (property only, no attribute) — which
+  capabilities to offer, in display order. `AttachmentCapability = 'files' | 'image' | 'camera'`.
+- `accept: string = ''` — a native-file-input-style accept string (e.g. `'image/*'` or
+  `'.pdf,.docx'`), forwarded to the hidden file input for the `files`/`image` capabilities. `image`
+  defaults it to `'image/*'` unless this prop overrides it; `files` always uses it as-is (empty
+  means "any file type").
+- `multiple: boolean = true` (reflected) — forwarded to the hidden file input's own `multiple`
+  attribute.
+- `disabled: boolean = false` (reflected)
+
+**Events:** `lyra-pick` (`detail: { capability: 'files' | 'image'; files: FileList }`) — fired once a
+file-backed capability's hidden input produces a real selection. The `FileList` is an independent
+snapshot (rehomed into a fresh `DataTransfer`), not a live reference to the input's own `.files` —
+see the gotcha below for why that distinction matters. `lyra-camera-request` (no detail — `detail`
+is `null`, not `undefined`, per the DOM spec's `CustomEventInit` default) — fired when the `camera`
+capability is activated; this component implements no capture UI of its own, the host owns
+everything from here (there's no single right answer for `getUserMedia` vs. `<input capture>` vs. a
+native wrapper's own camera API).
+
+**Slots:** none — capabilities are configured entirely via the `capabilities` prop.
+
+**CSS parts:** `trigger` (the single-capability button, only rendered when
+`capabilities.length === 1`), `menu` (the `lyra-menu` wrapper, only rendered when
+`capabilities.length > 1`).
+
+**Themeable custom properties:** shared tokens only — `--lyra-space-xs`, `--lyra-color-text`,
+`--lyra-icon-button-size`, `--lyra-focus-ring-*`, `--lyra-opacity-disabled`, `--lyra-radius`.
+
+**Optional peer deps:** none.
+
+```html
+<lyra-attachment-trigger .capabilities=${['files', 'image', 'camera']} accept=".pdf,.docx"
+  @lyra-pick=${(e) => queueFiles(e.detail.capability, e.detail.files)}
+  @lyra-camera-request=${openCameraFlow}
+></lyra-attachment-trigger>
+```
+
+**Known gotchas:**
+- `HTMLInputElement.files` is a *live* view in most browsers — clearing `input.value` after reading
+  `.files` (needed so re-picking the exact same file still fires another `change` event next time)
+  mutates that exact `FileList` object back to empty in place, not just detaches a stale reference.
+  A consumer reading `lyra-pick`'s `detail.files` even one microtask later (an `async` handler, a
+  queued upload) would otherwise observe an empty list — this component avoids that by rehoming the
+  selection into a fresh `DataTransfer` before emitting, but any other file-input-adjacent code
+  emitting `input.files` directly without that rehoming step has the same latent bug.
+- The `camera` capability never touches the hidden `<input type="file">` at all — it's scope-
+  limited by design to firing `lyra-camera-request` and nothing else.
+
+---
+
+## `lyra-kbd`
+
+A small chip representing a keyboard shortcut, rendering the platform-appropriate glyph for
+cross-platform modifier keys (⌘ on macOS, "Ctrl" elsewhere) from a single platform-neutral `keys`
+string. First-party invention (no Web Awesome equivalent).
+
+**Properties:**
+- `keys: string = ''` — a `+`-separated sequence of tokens, e.g. `"mod+k"` or `"mod+shift+p"`.
+  Recognized modifier tokens: `mod` (platform-neutral primary modifier — ⌘/"Command" on macOS,
+  "Ctrl"/"Control" elsewhere), `alt` (⌥/"Option" on macOS, "Alt" elsewhere), `shift` (⇧/"Shift"
+  always), `ctrl`/`control` (always the literal Control key, distinct from `mod`, for a shortcut
+  that's specifically Ctrl even on macOS). Anything else falls through to a small built-in map of
+  friendly labels (`enter` → `↵`/"Enter", `esc`/`escape` → "Esc"/"Escape", `tab`, `space`,
+  `backspace` → `⌫`/"Backspace", `delete` → "Del"/"Delete", `home`, `end`, `pageup` → "PgUp"/"Page
+  Up", `pagedown` → "PgDn"/"Page Down", the four `arrowup`/`arrowdown`/`arrowleft`/`arrowright` →
+  arrow glyphs, `plus`/`minus` → literal "+"/"−" as an escape hatch since `+` is the token
+  delimiter and can't appear as a literal token itself), or, failing that, renders as typed
+  (single letters/digits upper-cased).
+
+**Exported types/functions (also directly usable standalone):** `KbdKeyLabel { visual: string;
+word: string }` — one resolved token's rendered glyph and spelled-out word.
+`shortcutTokenLabel(rawToken: string, isMac: boolean): KbdKeyLabel` — resolves a single token,
+parameterized on `isMac` so both platform branches are unit-testable without spoofing `navigator`.
+`parseShortcut(keys: string, isMac: boolean): KbdKeyLabel[]` — splits and resolves a full `keys`
+string.
+
+**Events:** none — purely presentational.
+
+**Slots:** default — an escape hatch for fully custom key-cap content (e.g. an icon instead of a
+text glyph). When it has any real (non-whitespace) content, it replaces the `keys`-driven rendering
+entirely and this component stops asserting its own `aria-label`, leaving the slotted content to
+carry its own accessible name.
+
+**CSS parts:** `base` (the chip root), `key` (one per rendered token).
+
+**Themeable custom properties:** shared tokens only — `--lyra-space-xs`, `--lyra-color-surface`/
+`-border`/`-text-quiet`, `--lyra-radius`, `--lyra-font`.
+
+**Optional peer deps:** none.
+
+```html
+<lyra-kbd keys="mod+k"></lyra-kbd>
+<lyra-kbd keys="mod+shift+p"></lyra-kbd>
+<lyra-kbd keys="esc"></lyra-kbd>
+```
+
+Platform detection (`IS_MAC`, computed once at module scope, not per-instance/per-render, since a
+page's platform never changes mid-session) prefers `navigator.userAgentData` (Client Hints, so far
+Chromium-only) when available, falling back through `navigator.platform` (long-deprecated) and
+finally a `navigator.userAgent` substring check — all three are deprecated/non-standard to varying
+degrees but remain, in combination, the practical cross-browser way to answer "is this macOS" today.
+The rendered chip carries `role="img"` with a single spelled-out `aria-label` (e.g. "Command+K")
+rather than exposing each glyph/`+`-separator as separate accessible-tree text, since the individual
+pieces aren't real words and would read worse piecemeal than as one label — glyphs like ⌘/⇧/⌥ are
+not reliably announced by every screen reader/platform combination, which is exactly why the
+spelled-out word form exists at all.
+
+---
+
+## `lyra-result-card` / `lyra-result-field`
+
+A small, tightly-coupled pair giving any custom `lyra-tool-result-view` renderer (registered via
+`registerToolRenderer()` in `../tool-result-view/registry.js`) a consistent "small bordered card +
+label/value row" visual language, without each one hand-rolling its own box. Neither component has
+any code dependency on the tool-result-view registry itself — they're generically usable anywhere a
+small card/field shell is useful.
+
+### `lyra-result-card`
+
+A small bordered card shell. Purely visual, with no state of its own beyond slot-presence tracking.
+
+**Properties:**
+- `title: string = ''` — small heading for the card. Leave unset for an untitled card (e.g. a bare
+  block of `lyra-result-field` rows with no natural heading).
+
+**Events:** none.
+
+**Slots:** default (the card body — typically one or more `lyra-result-field` rows, though any
+content is accepted), `actions` (small header controls, e.g. a copy button, rendered alongside the
+title).
+
+**CSS parts:** `base` (outer bordered container), `header` (present in the DOM at all times so a
+later `slotchange` on `actions` is still observed, but `hidden` whenever there's no `title` and no
+`actions` content), `title`, `actions` (`hidden` whenever the slot has no assigned content), `body`.
+
+**Themeable custom properties:** shared tokens only — `--lyra-space-xs`/`-s`, `--lyra-color-border`/
+`-surface`/`-text`, `--lyra-radius`.
+
+### `lyra-result-field`
+
+A single label/value row — e.g. "Status: 200 OK" or "Duration: 340ms" — rendered as a dense
+"label: value" line by default, matching the compact, small-card presentation this pair exists for.
+
+**Properties:**
+- `label: string = ''` — the field name, e.g. "Status". Leave unset to render a value with no label.
+- `value: string = ''` — plain-text value, e.g. "200 OK". Ignored once the default slot carries real
+  content.
+
+**Events:** none.
+
+**Slots:** default — rich value content (e.g. a `lyra-chip` status badge, or a plain text override),
+taking precedence over `value` whenever it has any assigned content. "Real content" means any
+assigned *element* (even one with no text of its own, like an attribute-driven status badge) or any
+non-whitespace text node — both a rich slotted badge and a plain-text override are caught.
+
+**CSS parts:** `base` (row container), `label` (including its trailing colon), `value` (wrapper
+around either the slotted content or the plain `value` text).
+
+**Themeable custom properties:** shared tokens only — `--lyra-space-xs`, `--lyra-color-text`/
+`-text-quiet`, `--lyra-font`.
+
+**Optional peer deps:** none (either component).
+
+```html
+<lyra-result-card title="Weather">
+  <lyra-result-field label="Status" value="200 OK"></lyra-result-field>
+  <lyra-result-field label="Duration" value="340ms"></lyra-result-field>
+  <lyra-result-field label="Provider">
+    <lyra-chip tone="success">OpenWeather</lyra-chip>
+  </lyra-result-field>
+</lyra-result-card>
+```
+
+**Known gotchas:**
+- `HTMLElement.textContent` read on a shadow-DOM wrapper containing a `<slot>` does NOT include the
+  slot's assigned/projected light-DOM content — only literal fallback children of the `<slot>` tag
+  itself (there are none here). Asserting against `[part="value"]`'s own `.textContent` to check
+  rendered slotted content will read as empty even when the component is rendering correctly;
+  assert against the slot's `assignedNodes()`/`assignedElements()` instead.
+
+---
+
 ## Cross-cutting notes
 
 These apply across the whole library rather than to any one component: