@aceshooting/lyra-ui 1.2.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
@@ -245,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)
@@ -301,6 +327,10 @@ secondary line, when `sub` is set), `expand-icon`, `error`, `hint`
 - 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.
 
 ---
 
@@ -764,9 +794,12 @@ 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
@@ -826,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`)
@@ -846,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`).
@@ -1027,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.
 
@@ -1370,6 +1434,12 @@ click, or Enter/Space on the focused cell, fires `lyra-cell-click`.
   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)
@@ -1442,7 +1512,10 @@ color) and `--lyra-space-xs`.
   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.
+  `'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.
 
 ---
 
@@ -1753,6 +1826,23 @@ passthrough). Not a subclass of `LyraChart`.
 - `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
@@ -1761,10 +1851,11 @@ focused). `detail: { datasetIndex: number, index: number, label: string | undefi
 **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`, or the measured plot size) have changed since the last
-render. A `tickFormat` identity change alone (with everything else unchanged) does not force a redraw —
-in practice `tickFormat` is stable across a component's lifetime, and any data change that would make a
-different `tickFormat` output visible already changes `datasets`/`labels` too.
+`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.
 
@@ -2069,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: