@aceshooting/lyra-ui 3.6.0 → 3.8.0

package/llms-full.txt

@@ -36,8 +36,8 @@ composition without registration; for example, `components/empty/empty.class.js`
   `lyra-model-settings-panel`, `lyra-context-meter`, `lyra-dock-panel`, `lyra-document-preview`,
   `lyra-document-viewer`, `lyra-docx-viewer`, `lyra-email-viewer`, `lyra-calendar-viewer`, `lyra-archive-viewer`,
   `lyra-media-card`, `lyra-attachment-trigger`, `lyra-kbd`, `lyra-result-card`/`lyra-result-field`,
-  `lyra-avatar`, `lyra-card`, `lyra-stepper`, `lyra-segmented`, `lyra-diff-view`, `lyra-poll-status`,
-  `lyra-code-block-core` (needs the optional peer `shiki`)
+  `lyra-avatar`, `lyra-card`, `lyra-stepper`, `lyra-segmented`, `lyra-diff-view`, `lyra-stack-trace`,
+  `lyra-poll-status`, `lyra-code-block-core` (needs the optional peer `shiki`)
 - **Cross-cutting notes** — packaging notes that apply across the whole library
 
 ---
@@ -740,10 +740,15 @@ shadow-internal native button doesn't participate in an ancestor form's submissi
 
 **Properties:**
 - `variant: 'neutral' | 'brand' | 'success' | 'warning' | 'danger' = 'neutral'` (reflected)
-- `appearance: 'accent' | 'filled' | 'outlined' | 'plain' = 'filled'` (reflected) — `'accent'` is a
+- `appearance: 'accent' | 'filled' | 'outlined' | 'plain' | 'link' = 'filled'` (reflected) —
+  `'accent'` is a
   loud, high-contrast filled tier,
   distinct from `'filled'` for `variant="neutral"` specifically (`'filled'` reads the ambient
-  surface color there; `'accent'` reads a solid neutral fill)
+  surface color there; `'accent'` reads a solid neutral fill). `'link'` is a true inline-link tier:
+  zero chrome (no padding, border, border-radius, or `min-block-size` floor), underlined
+  (`text-underline-offset: var(--lyra-size-0-15rem)`), colored from `--lyra-button-accent` (the same token `'plain'`
+  uses, so `variant` still selects the link color) and inheriting the surrounding font-size/weight
+  — for a text link that flows within a sentence rather than a button-shaped control
 - `size: 'xs' | 's' | 'm' | 'l' | 'xl' = 'm'` (reflected)
 - `type: 'button' | 'submit' | 'reset' = 'button'`
 - `loading: boolean = false` (reflected) — shows an internal spinner and disables the button without
@@ -779,6 +784,7 @@ loud fill token), `--lyra-button-hover-brightness` (default `1.08`, the `:hover`
 <lyra-button variant="brand" appearance="filled">Save</lyra-button>
 <lyra-button variant="neutral" appearance="accent">Save</lyra-button>
 <lyra-button appearance="plain" aria-label="Close dialog"><svg slot="start">...</svg></lyra-button>
+<p>The message failed. <lyra-button appearance="link" variant="brand">Retry</lyra-button></p>
 ```
 
 **Known gotchas:**
@@ -1447,12 +1453,17 @@ accent edge and value tint).
 ## `lyra-table`
 
 Sort/select-aware data table. Sorting remains consumer-controlled; optional filtering, pagination,
-and loading chrome are built in while remaining controlled at the public API boundary.
+and loading chrome are built in while remaining controlled at the public API boundary. A
+`columns[].heatValue`-opted-in heat-tint mode paints a shared, normalized color-mix background across
+every tinted cell (auto-derived domain, or overridden via `heatTintScale`); `rowTotal`/`grandTotal`
+add a trailing totals column mirroring `expandedContent`'s leading one — `rowTotal(row)` renders
+per-row, `grandTotal(rows)` renders at its intersection with the footer row — both sharing `footer`'s
+own "consumer computes/renders" contract rather than assuming addition.
 
 **Properties:**
 - `columns: TableColumn<T>[] = []` (attribute: false) — `{ key, label, headerCell?, width?,
-  minWidth?, sortable?, align?: 'start'|'end', priority?: 'medium'|'low', sticky?: boolean |
-  'start' | 'end', footer?, cellStyle?, cell: (row) => unknown }` —
+  minWidth?, resizable?, sortable?, align?: 'start'|'end', priority?: 'medium'|'low', sticky?: boolean |
+  'start' | 'end', footer?, cellStyle?, heatValue?, cell: (row) => unknown }` —
   `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
@@ -1463,10 +1474,17 @@ and loading chrome are built in while remaining controlled at the public API bou
   sticky-bottom footer cell for that column, computed from every currently-rendered row (post-sort,
   pre-pagination) — e.g. a column total — omit it for a column with no footer value, and a
   `[part='foot']` (`<tfoot>`) only renders at all when at least one column defines `footer`;
-  `cellStyle` is applied directly to the generated `<td>` via `styleMap` — e.g. a computed heat-tint
+  `heatValue(row) => number | null | undefined` opts a column into heat-tint mode: its presence on
+  any column is the opt-in signal (no separate boolean), a `null`/`undefined` return excludes that
+  cell from both the domain and the tint ("no data", not "zero"), and every `heatValue`-defining
+  column shares one normalized `color-mix()` background scale (see `heatTintScale` below) painted
+  via the retheme-able `--lyra-table-heat-tint-lo`/`-hi` custom properties, matching `lyra-heatmap`'s
+  own ramp-token convention; `cellStyle` is applied directly to the generated `<td>` via `styleMap` — e.g. a computed heat-tint
   background a `cell()`-returned inner element can't paint into the cell's own padding — omit it for
   no per-cell style override (the default, unchanged output); `editable` enables double-click
   editing, `editValue` supplies the editor value, and `editType` selects `text` or `number`
+  `resizable` adds a pointer-driven `[part='resize-handle']` and emits `lyra-column-resize` with the
+  live width in CSS pixels; an explicit pixel `minWidth` is respected.
 - `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
@@ -1532,6 +1550,19 @@ and loading chrome are built in while remaining controlled at the public API bou
   button's label once they've been revealed)
 - `showAllColumns: boolean = false` (attribute `show-all-columns`, reflected) — forces responsive
   priority columns visible and is updated by the built-in reveal button
+- `heatTintScale?: { min?: number; max?: number }` (attribute: false) — overrides the auto-derived
+  heat-tint domain (min/max of every `heatValue` result across every currently-rendered row —
+  post-sort, pre-pagination, the same rows `footer(rows)` already sees). Unset (the default) computes
+  the domain automatically from the data, spanning every `heatValue`-defining column together — a
+  single shared scale across the whole grid, not one scale per column
+- `rowTotal?: (row: T) => unknown` (attribute: false) — renders a trailing `<td>`
+  (`[part='row-total-cell']`) on every body row holding this row's total. Same "consumer
+  computes/renders, table only positions" contract as the existing per-column `footer(rows)` — does
+  not assume addition, so a non-sum aggregate works identically. Omit for no trailing column at all
+  (unchanged output)
+- `grandTotal?: (rows: T[]) => unknown` (attribute: false) — renders the bottom-right cell (row-total
+  column × footer row). Only rendered when both `rowTotal` is set **and** at least one column defines
+  `footer` — otherwise there is no footer row for it to occupy, and this renders nothing
 
 **Events:** `lyra-sort` (`detail: { key }`, fired on sortable-header activation), `lyra-row-click`
 (`detail: { row }`), `lyra-load-more` (fired on the "load more" button), `lyra-columns-hidden-change`
@@ -1541,19 +1572,26 @@ and loading chrome are built in while remaining controlled at the public API bou
 `lyra-selection-change` (`detail: { keys }`) when selection is enabled, `lyra-filter-change`
 (`detail: { text }`), and `lyra-page-change` (`detail: { page }`) from the controlled
 filter/pagination surfaces, and `lyra-cell-edit` (`detail: { row, key, value }`) for editable
-columns
+columns, and `lyra-column-resize` (`detail: { key, width }`) on every resize drag step
 
 **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 `columnsHidden` is true), `foot` (the `<tfoot>`, only rendered when at least one
-column defines `footer`), `footer-row`, `footer-cell`, `expand-toggle-cell`, `row-expand-toggle`,
+column defines `footer`), `footer-row`, `footer-cell`, `row-total-cell` (each body row's trailing
+`<td>` holding `rowTotal(row)`, rendered only when `rowTotal` is set — the corresponding footer-row
+cell, holding `grandTotal`, is a `footer-cell` instead, matching every other footer cell),
+`expand-toggle-cell`, `row-expand-toggle`,
 `row-expand-icon`, `expanded-row`, `expanded-cell`, `filter-label`, `filter`, `loading`, and
-`pagination`, `cell-editor`, `group-row`, and `group-cell`
+`pagination`, `cell-editor`, `group-row`, `group-cell`, and `resize-handle`
 
 **Themeable custom properties:** `--lyra-table-max-height` (default `none`; controls the scrollable
-body's `max-block-size`).
+body's `max-block-size`). `--lyra-table-heat-tint-lo` (default `var(--lyra-color-brand-quiet)`) and
+`--lyra-table-heat-tint-hi` (default `var(--lyra-color-brand)`) — the `color-mix()` ramp endpoints
+for heat-tint mode's per-cell background, consulted only on columns/rows that define `heatValue`;
+`--lyra-table-resize-min-width` (default `var(--lyra-size-3rem)`) and
+`--lyra-table-resize-handle-opacity` (default `0.12`) control resizable-column behavior.
 
 **Optional peer deps:** none.
 
@@ -2501,16 +2539,95 @@ same color as `--lyra-heatmap-focus-ring-color`).
 
 ---
 
+## `lyra-sequence-strip`
+
+A compact, one-thin-cell-per-item strip visualizing a sequence of categorical states, with an
+optional secondary per-cell marker. Pure CSS/flex — no chart.js, no SVG, no canvas — sized/named
+consistently with the sparkline/heatmap family, but a glanceable *aggregate* visualization
+(`role="img"`, one summarizing `aria-label`) rather than a `role="list"` of separately-operable
+items: there is no per-cell keyboard focus and no per-cell click event, matching `<lyra-sparkline>`'s
+accessibility model rather than `<lyra-heatmap>`'s heavier canvas-plus-keyboard-roving one. Hovering a
+cell (pointer only) shows `[part="tooltip"]` with that item's label.
+
+**Properties:**
+- `items: SequenceStripItem[] = []` (attribute: false) — `{ id, category, marker?, label? }`;
+  `marker` renders a small bottom marker on that cell independent of the category color (e.g. a
+  subagent-dispatched turn); `label` is per-item hover-tooltip text, falling back to the matching
+  category's own `label` (or its `key`) when unset — not read by the auto-generated `aria-label`,
+  which summarizes by category/count only
+- `categories: SequenceStripCategory[] = []` (attribute: false) — `{ key, color, label? }`; `color`
+  is the cell background for every item whose `category` matches `key` (an item whose `category`
+  matches no entry renders `transparent`); `label` is used in the auto-generated `aria-label` summary
+  and as the hover-tooltip fallback text, falling back to `key` itself when unset
+- `orientation: 'horizontal' = 'horizontal'` (reflected) — only `'horizontal'` is supported today;
+  vertical is plausible future scope, not built speculatively without a motivating case
+- `accessibleLabel?: string` (attribute `accessible-label`) — overrides the auto-generated
+  `aria-label` (a per-category "label: count" summary, e.g. `"Text: 2, Tool: 1"`). Unset computes the
+  summary from `items`/`categories`
+
+**Events:** none.
+
+**Slots:** none.
+
+**CSS parts:** `base` (the root strip, `role="img"`), `cell` (each item's cell, background-colored
+by its category), `marker` (the small bottom marker on a cell whose item sets `marker: true`),
+`tooltip` (the hover tooltip showing the hovered item's label, hidden until a cell is hovered).
+
+**Themeable custom properties:** `--lyra-sequence-strip-height` (default `1.5rem` — the strip's
+block-size) and `--lyra-sequence-strip-marker-color` (default `var(--lyra-color-text)` — the
+`[part="marker"]` fill); the tooltip also consumes shared tokens `--lyra-color-surface`,
+`--lyra-color-text`, `--lyra-font-size-xs`, `--lyra-radius`, and `--lyra-shadow`.
+
+**Optional peer deps:** none.
+
+```html
+<lyra-sequence-strip></lyra-sequence-strip>
+<script>
+  const strip = document.querySelector('lyra-sequence-strip');
+  strip.categories = [
+    { key: 'text', color: '#4f46e5', label: 'Text' },
+    { key: 'tool', color: '#16a34a', label: 'Tool' },
+  ];
+  strip.items = [
+    { id: '1', category: 'text', label: 'Turn 1: text' },
+    { id: '2', category: 'tool', marker: true, label: 'Turn 2: tool call' },
+    { id: '3', category: 'text', label: 'Turn 3: text' },
+  ];
+</script>
+```
+
+**Known gotchas:**
+- there is no `lyra-cell-click`/keyboard-interaction model at all — unlike `lyra-heatmap`'s
+  canvas cells, a strip cell is purely a hover target; build a click handler outside this component
+  (e.g. on a wrapping element) if per-item activation is needed.
+- an `items` entry whose `category` has no matching `categories` entry still renders its own cell
+  (background `transparent`) rather than being dropped, so a strip stays the same length as `items`
+  regardless of `categories` coverage.
+
+---
+
 ## `lyra-graph`
 
 A force-directed node-link diagram with pan/zoom/drag, built on `d3-force`.
 
 **Properties:**
 - `nodes: GraphNode[] = []` (attribute: false) — `GraphNode { id: string; label?: string;
-  accessibleLabel?: string; description?: string; radius?: number; color?: string }`;
+  accessibleLabel?: string; description?: string; radius?: number; color?: string; type?: string }`;
   `accessibleLabel` supplies richer spoken text than the visible label, while `description` renders
   as native SVG `<title>` tooltip text. `radius` is clamped to `[6, 24]` (an unset/non-finite value
-  falls back to the midpoint, `15`) so a node can never render invisibly small or absurdly large
+  falls back to the midpoint, `15`) so a node can never render invisibly small or absurdly large.
+  `type` is a key into `nodeTypes` (matched by `GraphNodeType.id`); unknown/absent renders as an
+  untyped default circle with the token fill, but an unmatched `type` still participates in
+  `hiddenTypes` filtering by its raw string value
+- `nodeTypes: GraphNodeType[] = []` (attribute: false) — `GraphNodeType { id: string; label: string;
+  color?: string; shape?: 'circle' | 'square' | 'diamond' }`, one entry per `GraphNode.type` value:
+  `label` feeds the spoken "typed node" summary, and `shape`/`color` drive rendering per node.
+  Per-node fill resolution precedence is `GraphNode.color` (most specific) > the matched
+  `GraphNodeType.color` > an ordered categorical fallback palette assigned by the type's index in
+  `nodeTypes` (`--lyra-graph-cat-1` through `-8`, wrapping every 8 entries) > the untyped
+  `--lyra-node-fill` default; both data-driven color sources are sanitized the same way as
+  `GraphNode.color` itself. A typed node with no matching `nodeTypes` entry renders as a plain
+  circle with the untyped default fill
 - `links: GraphLink[] = []` (attribute: false) — `GraphLink { id?: string; source: string; target:
   string; width?: number; label?: string; accessibleLabel?: string; description?: string; directed?:
   boolean; color?: string; dash?: number[] }` (source/target are node ids). `directed` adds an
@@ -2535,19 +2652,65 @@ A force-directed node-link diagram with pan/zoom/drag, built on `d3-force`.
   (keyed by node **id**, not array index/order) instead of `forceSimulation()`'s own random start,
   and settles the simulation synchronously instead of animating the settle (same effect
   `prefers-reduced-motion` has, see gotchas)
-
-**Events:** `lyra-node-click` (`detail: { id }`), `lyra-link-click` (`detail: { source, target,
-id? }`; the optional `id` is the stable `GraphLink.id` supplied by the caller)
+- `showEdgeLabels: boolean = false` (attribute `show-edge-labels`) — draws each resolved
+  (non-dangling) link's `label` as visible SVG text (`[part="link-label"]`) at the segment midpoint.
+  Off by default: `GraphLink.label` stays spoken/tooltip-only, matching pre-existing behavior, unless
+  this is set
+- `edgeLabelMinZoom: number = 0.6` (attribute `edge-label-min-zoom`) — below this zoom scale, every
+  drawn edge label is hidden (toggled via a `data-edge-labels-hidden` attribute on the zoomed `<g>`,
+  not a Lit re-render, so it tracks pan/zoom smoothly). Ignored entirely when `showEdgeLabels` is
+  `false`
+- `layout: 'force' | 'layered' = 'force'` — `'force'` runs the `d3-force` simulation described
+  throughout this section, unchanged. `'layered'` swaps in a deterministic Sugiyama-lite layered
+  layout instead (longest-path layering, barycenter crossing reduction, cycle-safe — back edges are
+  reversed only for layering, never mutating caller data): positions are computed synchronously
+  with no settle animation, sized from each node's own radius and spaced by `linkDistance` (the
+  layer gap) and a fixed 12px in-layer gap. Node drag is disabled in this mode (dragging would fight
+  a computed layout) and `chargeStrength` becomes a documented no-op; pan/zoom, keyboard roving,
+  `focusNode()`/`fit()`, hulls, edge labels, and `hiddenTypes` filtering all work identically to
+  force mode. Switching `layout` at runtime repositions every node without a tween. The layering
+  algorithm itself lives in the standalone, dependency-free `layeredLayout()` export
+  (`@aceshooting/lyra-ui/internal/layered-layout`), reusable by any other layered-diagram consumer
+- `renderer: 'svg' | 'canvas' = 'svg'` — `'canvas'` swaps the per-node/per-link SVG DOM for a single
+  DPR-aware `<canvas>`; every event/method/property behaves identically to `'svg'`, with hit-testing
+  resolved via an offscreen color-picking canvas instead of DOM event targets. Trade-offs: no
+  `::part(node)`/`::part(link)` styling (pixels, not elements — theme via cssprops instead), no
+  native SVG `<title>` tooltip (replaced by `part="tooltip"`), and a drawn focus ring instead of a
+  CSS one. Keyboard roving/announcements are preserved through an offscreen `part="cursor-item"`
+  button per node/link/hull.
+
+**Methods:** `focusNode(id, options?: { zoom? })` and `fit(options?: { padding?: number })` control the
+camera; `getNodePosition(id)` returns the current `{ x, y }` in graph-local drawing coordinates, or
+`undefined` when the id is not currently simulated.
+
+**Events:** `lyra-node-click` (`detail: { id, x, y }`, where `x` and `y` are the clicked node's current
+local drawing coordinates), `lyra-link-click` (`detail: { source, target,
+id? }`; the optional `id` is the stable `GraphLink.id` supplied by the caller), `lyra-node-enter`/
+`lyra-node-leave` (`detail: { id }`, hover start/end, suppressed while dragging/panning),
+`lyra-link-enter`/`lyra-link-leave` (`detail: { source, target, id? }`, same hover contract),
+`lyra-node-expand` (`detail: { id }`, a node was double-activated — native `dblclick`, or two
+Enter/Space activations within 500ms — regardless of `GraphNode.expandable`), `lyra-community-click`
+(`detail: { id }`, a hull was activated)
 
 **Slots:** none.
 
 **CSS parts:** `base`, `svg`, `node`, `link`, `arrowhead` (the marker path shared by directed links),
-`label`, `live-region`, `data-list`, `empty`
+`label`, `link-label` (a drawn edge label, only rendered when `showEdgeLabels` is set),
+`expand-indicator` (the "+" badge on a node with `expandable: true`), `focus-halo` (the persistent
+ring tracking `focusId`'s node), `hull` (a community hull), `community-label`,
+`live-region`, `data-list`, `empty`, `canvas`/`tooltip`/`cursor-items`/`cursor-item`
+(`renderer="canvas"` only — the drawing surface, its hover tooltip replacing the SVG `<title>`, and
+the offscreen keyboard-roving items)
 
 **Themeable custom properties:** `--lyra-node-fill` (set inline per-node from `GraphNode.color`,
 falls back to `--lyra-color-brand`) and `--lyra-link-color` (set inline per-link from
 `GraphLink.color`, falling back to `--lyra-color-border`); also uses `--lyra-color-text` +
 `--lyra-font` (label text), `--lyra-focus-ring-*` (node/link `:focus-visible` outline).
+`--lyra-graph-cat-1` through `-8` — the ordered categorical fallback palette for a typed node with
+no `GraphNodeType.color`, assigned by the type's index in `nodeTypes` (wraps every 8 entries);
+declared centrally in `tokens.styles.ts` so this stays the same default across components.
+`--lyra-graph-edge-label-halo` (default `var(--lyra-color-surface)`) — the legibility halo painted
+behind a drawn `[part="link-label"]` (via `paint-order: stroke`).
 
 **Optional peer deps:** `d3-force`, `d3-drag`, `d3-zoom`, `d3-selection` (all four required
 together; lazy-`import()`ed once per page, `console.warn` once and renders empty if missing —
@@ -2610,6 +2773,26 @@ install with `pnpm add d3-force d3-drag d3-zoom d3-selection`).
 - the `<svg part="svg">` now carries `role="group"` and an `aria-label` summarizing the node/link
   counts (e.g. "Node-link diagram with 5 nodes and 4 links"), and node `<text part="label">`s are
   `aria-hidden="true"` (their content is already covered by each node's own `aria-label`).
+- `nodeTypes` and `showEdgeLabels` are live-reactive post-mount: either changing re-scans/rebinds the
+  cached per-node and per-link DOM element arrays, alongside the existing `simNodes`/`simLinks`
+  structural-change trigger — no need to also touch `nodes`/`links` to see a type/shape/color or
+  edge-label change take effect.
+- when `showEdgeLabels` is `false` (the default), a resolved link renders as a bare `<line
+  part="link">` with no extra wrapping element, so existing consumers who never set it see
+  byte-for-byte identical link DOM; setting it wraps each link's `<line>` and its
+  `[part="link-label"]` `<text>` together. `edgeLabelMinZoom`'s hide/show gate is applied once at
+  mount (against d3-zoom's known identity transform) as well as on every subsequent pan/zoom, so
+  labels never wrongly start visible before the first user gesture.
+
+**Selection & focus:** `selectionMode: 'none' | 'single' | 'multiple' = 'none'` (attribute
+`selection-mode`) gates click/keyboard selection; the component never mutates
+`selectedNodeIds: string[] = []` / `selectedLinkIds: string[] = []` (both attribute: false) itself,
+only emits `lyra-selection-change` (`detail: { nodeIds, linkIds }`) — the host assigns them back,
+mirroring `lyra-heatmap`'s `selectedCell` contract. `communities: GraphCommunity[] = []` (attribute:
+false) draws one translucent convex-hull blob per entry behind links/nodes. `focusId: string | null =
+null` (attribute `focus-id`) tracks a persistent focus ring (`[part="focus-halo"]`) around one node;
+`focusNode(id, options?)` and `fit(options?)` are the imperative camera-tween counterparts (pan/zoom
+to a node, or to fit the whole graph), both resolving once the tween settles.
 
 ---
 
@@ -2734,6 +2917,816 @@ indentation), plus the shared tokens listed above.
 
 ---
 
+# Flow canvas
+
+## `lyra-flow-canvas`
+
+A pannable/zoomable DAG workflow canvas: positions HTML node cards, draws SVG edges between their
+handles, runs a shared layered auto-layout for unpositioned nodes, and owns all selection/drag/
+connect interaction as controlled events. Readonly (viewer) by default; opt into editor gestures
+individually via `nodes-draggable`, `connectable`, `droppable`. Never mutates `nodes` or `edges`
+itself — every edit intent is an event the host applies, mirroring `lyra-stepper`/`lyra-table`'s
+controlled-component contract.
+
+**Properties:**
+- `nodes: FlowNode[] = []` (attribute: false) — `FlowNode { id: string; type?: string; position?: {
+  x, y }; data?: Record<string, unknown>; accessibleLabel?: string; inputs?: FlowHandle[]; outputs?:
+  FlowHandle[] }`; a node with no `position` is placed by the layered auto-layout, and `data.label`/
+  `data.description` feed the default `<lyra-flow-node>` card when no matching light-DOM child exists
+- `edges: FlowEdge[] = []` (attribute: false) — `FlowEdge { id: string; source: string; target:
+  string; sourceHandle?: string; targetHandle?: string; label?: string; tone?: 'accent' | 'success' |
+  'warning' | 'danger' | 'neutral' }` (source/target are node ids; `label` draws at the edge midpoint,
+  unlike `lyra-graph`'s spoken-only `GraphLink.label`)
+- `orientation: 'horizontal' | 'vertical' = 'horizontal'` (reflected) — downstream layout/handle axis
+- `nodesDraggable: boolean = false` (attribute `nodes-draggable`)
+- `connectable: boolean = false`
+- `droppable: boolean = false` — accepts drops carrying the `FLOW_PALETTE_MIME_TYPE` payload a
+  `lyra-node-palette` drag sets, emitting `lyra-node-add`
+- `locked: boolean = false` (reflected) — freezes pan/zoom/drag/connect without touching the other
+  gesture flags
+- `selectedNodeIds: string[] = []`, `selectedEdgeIds: string[] = []` (attribute: false) — controlled;
+  the host assigns these back from `lyra-selection-change`
+- `minZoom: number = 0.25` (attribute `min-zoom`), `maxZoom: number = 2` (attribute `max-zoom`)
+- `grid: number = 8` — snap step in content px for drags/nudges/drop positions (`0` disables
+  snapping); also the dotted background's base spacing
+- `layerGap: number = 64` (attribute `layer-gap`), `nodeGap: number = 24` (attribute `node-gap`) —
+  auto-layout layer/sibling spacing
+- `decorations: FlowRunDecorations | null = null` (attribute: false) — `Record<nodeOrEdgeId,
+  FlowRunDecoration>`, `FlowRunDecoration { status: 'pending'|'running'|'success'|'error'|'denied';
+  progress?: number; durationMs?: number; detail?: string }`; pushed onto adopted `lyra-flow-node`
+  cards, typically supplied via a `lyra-flow-run-overlay`
+- `accessibleLabel: string | null = null` (attribute `aria-label`)
+- `viewport` (read-only getter) — `{ x, y, zoom }`, the current pan/zoom state
+
+**Methods:** `setViewport({ x, y, zoom })`, `zoomIn()`, `zoomOut()`, `resetZoom()`,
+`fit(options?: { padding?: number })` (frames every node), `focusNode(id, options?: { zoom? })`
+(pans/zooms to one node and moves roving focus onto it), `toContentPoint(clientX, clientY)` (maps a
+pointer position to content coordinates, RTL-aware), `registerCompanion(cb: (snapshot:
+FlowStructureSnapshot) => void): () => void` — the subscription `lyra-flow-minimap` uses to read
+live node/edge/viewport geometry without this canvas ever importing the minimap.
+
+**Events:** `lyra-node-click` (`detail: { id }`), `lyra-edge-click` (`detail: { id, source, target
+}`), `lyra-selection-change` (`detail: { nodeIds, edgeIds }`), `lyra-node-move` (`detail: { id,
+position, previous }`), `lyra-connect` (`detail: { source, target, sourceHandle, targetHandle }`),
+`lyra-node-add` (`detail: { type, position }`, from a palette drop), `lyra-selection-delete`
+(`detail: { nodeIds, edgeIds }`), `lyra-viewport-change` (`detail: { x, y, zoom }`),
+`lyra-layout-change` (`detail: { positions }`, fired after an auto-layout pass places previously
+unpositioned nodes).
+
+**Slots:** default (`lyra-flow-node` children adopted by `node-id`; a non-matching child is ignored
+with a console warning), `top-start`, `top-end` (floating corner overlays), `bottom-start` (e.g.
+`lyra-flow-controls`), `bottom-end` (e.g. `lyra-flow-minimap`).
+
+**CSS parts:** `base`, `viewport`, `background`, `edges`, `edge`, `edge-label`, `arrowhead`, `stub`
+(a dangling-edge stub line), `connection-line` (in-progress connect gesture), `node`, `empty`,
+`live-region`, `edge-list` (a visually hidden list of every edge).
+
+**Themeable custom properties:** `--lyra-flow-canvas-grid-size` (default `8px`, dotted background
+spacing), `--lyra-flow-canvas-march-duration` (default `var(--lyra-transition-ambient)`, running-edge
+march animation duration).
+
+**Optional peer deps:** none.
+
+```html
+<lyra-flow-canvas id="canvas" nodes-draggable connectable droppable style="height:480px"></lyra-flow-canvas>
+<lyra-flow-controls slot="bottom-start" for="canvas"></lyra-flow-controls>
+<lyra-flow-minimap slot="bottom-end" for="canvas"></lyra-flow-minimap>
+<script>
+  const canvas = document.getElementById('canvas');
+  canvas.nodes = [
+    { id: 'a', data: { label: 'Fetch' } },
+    { id: 'b', data: { label: 'Transform' } },
+  ];
+  canvas.edges = [{ id: 'a-b', source: 'a', target: 'b' }];
+  canvas.addEventListener('lyra-node-move', (e) => {
+    canvas.nodes = canvas.nodes.map((n) => (n.id === e.detail.id ? { ...n, position: e.detail.position } : n));
+  });
+</script>
+```
+
+**Known gotchas:**
+- Fully controlled: `nodes`/`edges`/`selectedNodeIds`/`selectedEdgeIds` are never mutated
+  internally — `lyra-node-move`, `lyra-selection-change`, `lyra-connect`, `lyra-node-add`, and
+  `lyra-selection-delete` are all requests the host applies back, same contract as `lyra-table`.
+- Auto-layout (via the dependency-free `layeredLayout()` util) only ever positions nodes that are
+  missing an explicit `position`; a node the host has already positioned is left exactly where it is
+  and used as a fixed anchor for the rest of the layout pass.
+- `droppable` only accepts drags carrying the exact `FLOW_PALETTE_MIME_TYPE` MIME type a
+  `lyra-node-palette` drag sets — the two components can never disagree on the payload shape because
+  they share one exported constant.
+- Pan/drag/zoom track the pointer's physical direction; under an RTL ancestor the pan and node-drag
+  deltas are mirrored so content still visually follows the cursor, matching every other
+  RTL-mirrored surface in this library.
+
+---
+
+## `lyra-flow-node`
+
+The card a workflow node renders as: header/body/toolbar chrome, tool-lifecycle status tones, and
+the named connection-handle elements edges anchor to. Used as `lyra-flow-canvas`'s default card and
+as a slotted override; also renders standalone (palette previews, docs). Purely presentational —
+activation, selection, movement, and connection are all `lyra-flow-canvas` events; this component
+owns none of that.
+
+**Properties:**
+- `nodeId: string = ''` (attribute `node-id`)
+- `heading: string = ''`
+- `status: 'pending' | 'running' | 'success' | 'error' | 'denied' | null = null` (reflected)
+- `progress: number | null = null` — renders a determinate `[part="progress"]` bar when set
+- `statusDetail: string = ''` (attribute `status-detail`) — appended to the status line
+- `durationMs: number | null = null` (attribute `duration-ms`) — formatted into the status line
+- `selected: boolean = false` (reflected)
+- `inputs: FlowHandle[] = [{ id: 'in' }]`, `outputs: FlowHandle[] = [{ id: 'out' }]` (attribute:
+  false) — `FlowHandle { id: string; label?: string }`
+- `orientation: 'horizontal' | 'vertical' = 'horizontal'` (reflected) — which physical edge handles
+  render on; mirrors the adopting canvas's own `orientation`
+
+**Events:** none — purely presentational, activation/drag/connect all live on `lyra-flow-canvas`.
+
+**Slots:** default (body content), `icon` (leading header glyph), `header` (replaces the built-in
+heading row entirely), `toolbar` (action row at the block-end edge).
+
+**CSS parts:** `base`, `header`, `icon`, `heading`, `status` (never color-only — always paired with
+text), `progress`, `body`, `toolbar`, `handle` (every handle dot), `handle-input`, `handle-output`.
+
+**Themeable custom properties:** `--lyra-flow-node-min-inline-size` (default `11rem`).
+
+**Optional peer deps:** none.
+
+```html
+<lyra-flow-node node-id="a" heading="Fetch" status="running" progress="40"></lyra-flow-node>
+```
+
+**Known gotchas:**
+- A running node's card pulses (`?data-pulse`) unless `prefers-reduced-motion` is set — the same
+  reduced-motion exception every animated surface in this library follows.
+- `status` drives a status chip with a localized label plus `statusDetail`/`durationMs`, never a
+  color-only indicator.
+
+---
+
+## `lyra-flow-minimap`
+
+A corner overview map of a `lyra-flow-canvas`: scaled node rectangles plus a draggable viewport
+rectangle, for orientation and fast navigation on canvases larger than the screen. Draws no edges
+(nodes only, matching the React Flow/n8n minimap convention) and never reads `nodes` itself —
+geometry always comes from the canvas's `registerCompanion()` snapshots, so the two can never
+disagree.
+
+**Properties:**
+- `for: string = ''` — id of the target `lyra-flow-canvas`; when empty, the nearest ancestor canvas
+  is used (the slotted-into-a-corner-slot case, the primary wiring)
+- `label: string = ''` — accessible name for the map region; falls back to a host `aria-label`, then
+  a localized default
+
+**Events:** none.
+
+**Slots:** none.
+
+**CSS parts:** `base`, `map` (the scaled SVG), `node` (one rect per node), `viewport` (the
+draggable, focusable view rectangle).
+
+**Themeable custom properties:** `--lyra-flow-minimap-inline-size` (default `12rem`),
+`--lyra-flow-minimap-block-size` (default `8rem`).
+
+**Optional peer deps:** none.
+
+```html
+<lyra-flow-canvas id="canvas" style="height:480px">
+  <lyra-flow-minimap slot="bottom-end" for="canvas"></lyra-flow-minimap>
+</lyra-flow-canvas>
+```
+
+**Known gotchas:**
+- Never resolves `nodes`/`edges` on its own — it subscribes to `registerCompanion()` and repaints
+  from whatever snapshot the canvas last pushed, so it can only ever show what the canvas itself
+  currently renders.
+- Dragging the viewport rectangle calls the canvas's `setViewport()` directly; there's no separate
+  event to wire up.
+
+---
+
+## `lyra-flow-controls`
+
+The canvas's button cluster: zoom in/out, fit, and interaction lock, so every flow surface ships the
+same affordances without hosts rebuilding them. Manipulates only view state, never `nodes`/`edges` —
+no editing commands live here.
+
+**Properties:**
+- `for: string = ''` — id of the target `lyra-flow-canvas`; empty resolves to the nearest ancestor
+- `orientation: 'vertical' | 'horizontal' = 'vertical'` (reflected) — button-cluster layout axis
+- `hideLock: boolean = false` (attribute `hide-lock`) — omits the lock/unlock toggle button
+
+**Events:** none dispatched directly — each button calls the resolved canvas's own `zoomIn()`/
+`zoomOut()`/`fit()`, or toggles its `locked` property.
+
+**Slots:** default — extra host buttons appended to the cluster, styled by the same group.
+
+**CSS parts:** `base` (the `role="group"` wrapper), `zoom-in`, `zoom-out`, `fit`, `lock` (omitted
+when `hideLock`).
+
+**Themeable custom properties:** shared tokens only.
+
+**Optional peer deps:** none.
+
+```html
+<lyra-flow-canvas id="canvas" style="height:480px">
+  <lyra-flow-controls slot="bottom-start" for="canvas"></lyra-flow-controls>
+</lyra-flow-canvas>
+```
+
+**Known gotchas:**
+- `for` resolution is identical to `lyra-flow-minimap`/`lyra-flow-run-overlay`: an explicit id, else
+  the nearest ancestor canvas — none of the three companions import `LyraFlowCanvas` as a value, only
+  its types, so registration order between them and the canvas never matters.
+
+---
+
+## `lyra-node-palette`
+
+The searchable, categorized node library for workflow editors: drag an item onto a canvas, or place
+it by keyboard. Never creates nodes or touches a canvas's data itself — the drop/place handshake ends
+at `lyra-node-add`/`lyra-palette-place`; the host mutates `nodes`. Fully decoupled from
+`lyra-flow-canvas` (no `for` resolution, unlike the other three companions) — it only needs to agree
+with a `droppable` canvas on the `FLOW_PALETTE_MIME_TYPE` drag payload shape.
+
+**Properties:**
+- `items: PaletteItem[] = []` (attribute: false) — `PaletteItem { type: string; label: string;
+  description?: string; category?: string; keywords?: string[]; icon?: unknown; disabled?: boolean }`;
+  `type` is the `FlowNode.type` a placement/drop creates, `category` groups items under
+  first-appearance-ordered headings, `disabled` renders an item visible but not draggable/placeable
+- `label: string = ''` — accessible name for the search field/listbox
+- `accessibleLabel: string | null = null` (attribute `aria-label`) — overrides the listbox's
+  computed accessible name; wins over `label` and the localized default, and attribute-reflects
+  from a host-level `aria-label`
+
+**Events:** `lyra-palette-place` (`detail: { type }`, a pointer click or Enter/Space — the
+click/keyboard alternative to dragging), `lyra-select` (`detail: { item }`, emitted alongside
+`lyra-palette-place` on both gestures, carrying the full item).
+
+**Slots:** `header` (content above the search field, e.g. a heading or tabs), `footer` (content
+below the list).
+
+**CSS parts:** `base`, `search`, `list` (the listbox), `group-header`, `item`, `item-icon`,
+`item-label`, `item-description`, `empty` (no-results message), `live-region` (result-count
+announcement).
+
+**Themeable custom properties:** shared tokens only.
+
+**Optional peer deps:** none.
+
+```html
+<lyra-node-palette id="palette"></lyra-node-palette>
+<lyra-flow-canvas id="canvas" droppable style="height:480px"></lyra-flow-canvas>
+<script>
+  document.getElementById('palette').items = [
+    { type: 'http-request', label: 'HTTP Request', category: 'Actions' },
+    { type: 'transform', label: 'Transform', category: 'Actions' },
+  ];
+  document.getElementById('canvas').addEventListener('lyra-node-add', (e) => {
+    console.log('drop payload type:', e.detail.type, e.detail.position);
+  });
+</script>
+```
+
+**Known gotchas:**
+- A drag from this palette carries `FLOW_PALETTE_MIME_TYPE` as its `DataTransfer` type — only a
+  `droppable` `lyra-flow-canvas` (or a host reimplementing the same MIME type) accepts it.
+- Clicking or activating an item by keyboard fires `lyra-palette-place`/`lyra-select` immediately, no
+  drag required — the host decides where the new node lands (there's no pointer position to derive
+  one from on a keyboard placement).
+
+---
+
+## `lyra-flow-run-overlay`
+
+Execution-state presentation for a `lyra-flow-canvas`: pushes a `FlowRunDecorations` map into the
+resolved canvas (the canvas itself renders the node/edge paint) and renders a compact run-summary
+strip. Does not execute, poll, or time anything — pure pushed state; `durationMs` is host-computed.
+
+**Properties:**
+- `for: string = ''` — id of the target `lyra-flow-canvas`; empty resolves to the nearest ancestor
+- `decorations: FlowRunDecorations = {}` (attribute: false) — `Record<nodeOrEdgeId,
+  FlowRunDecoration>`, pushed verbatim onto the resolved canvas's own `decorations` property
+- `hideSummary: boolean = false` (attribute `hide-summary`) — omits the "{done} of {total} steps
+  complete" strip, keeping only the decoration push
+- `label: string = ''` — accessible name for the summary strip
+
+**Events:** none dispatched directly.
+
+**Slots:** default — extra host chrome appended to the strip (e.g. a cancel button or a usage
+badge).
+
+**CSS parts:** `base`, `summary` (the "{done} of {total} steps complete" line), `count` (one per
+status present, text + tone dot, never color-only), `live-region` (step-transition announcement).
+
+**Themeable custom properties:** shared tokens only.
+
+**Optional peer deps:** none.
+
+```html
+<lyra-flow-canvas id="canvas" style="height:480px">
+  <lyra-flow-run-overlay slot="top-start" for="canvas"></lyra-flow-run-overlay>
+</lyra-flow-canvas>
+<script>
+  document.querySelector('lyra-flow-run-overlay').decorations = {
+    a: { status: 'success', durationMs: 820 },
+    b: { status: 'running', progress: 40 },
+  };
+</script>
+```
+
+**Known gotchas:**
+- Purely a pushed-state conduit: it never starts, stops, or times a run itself — the host recomputes
+  `decorations` (including `durationMs`) on whatever cadence its own execution engine ticks at.
+- `for` resolution matches `lyra-flow-minimap`/`lyra-flow-controls`.
+
+---
+
+# Knowledge graph & RAG exploration
+
+## `lyra-graph-legend`
+
+A node-type legend for a paired `lyra-graph`: one swatch + label + count row per node type, doubling
+as visibility filters. Never reads or writes a graph directly — the host forwards `types` in from
+`graph.nodeTypes` and `hiddenTypes` back out to `graph.hiddenTypes` on `lyra-visibility-change`, the
+same event-decoupled contract every sibling in this family follows.
+
+**Properties:**
+- `types: LyraGraphLegendType[] = []` (attribute: false) — `{ id: string; label: string; color?:
+  string; shape?: 'circle' | 'square' | 'diamond' }`, the exact `lyra-graph.nodeTypes` entry shape
+  (declared locally, not imported, so this stays a zero-dependency component)
+- `counts?: Record<string, number>` (attribute: false) — optional per-type count shown alongside the
+  label
+- `hiddenTypes: string[] = []` (attribute: false) — controlled; the host assigns this back from
+  `lyra-visibility-change`
+- `interactive: boolean = true` (reflected) — renders each row as a toggle `<button>`; `false` renders
+  plain, non-interactive rows
+- `label: string = ''` — accessible name for the `role="group"` wrapper
+
+**Events:** `lyra-visibility-change` (`detail: { hiddenTypes }`, the complete updated array, fired
+after each toggle).
+
+**Slots:** none.
+
+**CSS parts:** `base`, `item` (a `<button>` when `interactive`, a plain `<div>` otherwise), `swatch`,
+`label`, `count`, `live-region` (the visually hidden filter-toggle announcement).
+
+**Themeable custom properties:** no component-local tokens; reads `--lyra-graph-cat-1` through `-8`
+(the same computed-style fallback palette `lyra-graph`/`lyra-word-cloud` use) plus shared tokens.
+
+**Optional peer deps:** none.
+
+```html
+<lyra-graph-legend id="legend"></lyra-graph-legend>
+<lyra-graph id="graph" style="height:480px"></lyra-graph>
+<script>
+  const graph = document.getElementById('graph');
+  const legend = document.getElementById('legend');
+  legend.types = [{ id: 'person', label: 'Person', color: '#0969da' }, { id: 'org', label: 'Organization' }];
+  legend.addEventListener('lyra-visibility-change', (e) => {
+    legend.hiddenTypes = e.detail.hiddenTypes;
+    graph.hiddenTypes = e.detail.hiddenTypes;
+  });
+</script>
+```
+
+**Known gotchas:**
+- Ships no coupling to `lyra-graph`'s optional `d3-force`/`d3-drag`/`d3-zoom`/`d3-selection` peers —
+  `types`/`counts`/`hiddenTypes` are plain data the host derives from a graph, never a live reference
+  to one.
+
+---
+
+## `lyra-entity-card`
+
+A dossier card for one knowledge-graph entity: type badge, description, key/value property rows,
+degree, community chip, plus a built-in "focus in graph" action. Never fetches or focuses a graph
+itself — `lyra-entity-activate` is a request a host routes into `lyra-graph`'s own
+`focusNode(id, options?)`.
+
+**Properties:**
+- `entity: LyraEntity | null = null` (attribute: false) — `LyraEntity { id: string; label: string;
+  type?: string; description?: string; properties?: Record<string, string | number>; degree?:
+  number; communityId?: string }`; field names deliberately mirror `lyra-graph`'s `GraphNode`
+  additions, so a graph node adapts into a `LyraEntity` with no mapping table; `null` renders the
+  empty state
+- `types: NodeTypeStyle[] = []` (attribute: false) — the same `lyra-graph.nodeTypes`/
+  `lyra-graph-legend.types` entry shape, resolving `entity.type` to a label/color/shape for the badge
+- `communityLabel: string = ''` (attribute `community-label`) — override text for the community chip
+- `showFocusButton: boolean = true` (attribute `show-focus-button`)
+
+**Events:** `lyra-entity-activate` (`detail: { id }`, the built-in focus button was activated).
+
+**Slots:** default (extra body content below the property rows, e.g. a `lyra-neighbor-list`),
+`actions` (extra header actions alongside the built-in focus button).
+
+**CSS parts:** `base`, `header`, `type-badge`, `title` (`role="heading" aria-level="3"` by default),
+`description`, `properties`, `property` (one key/value row), `degree`, `community`, `actions`,
+`focus-button`, `empty` (shown when `entity` is `null`).
+
+**Themeable custom properties:** shared tokens only; a data-driven `entity.type` color is applied as
+sanitized inline `--lyra-badge-*` overrides on the type badge only (the one "type color is
+data-driven by design" exception this library already grants graph nodes) — every other color comes
+from tokens.
+
+**Optional peer deps:** none.
+
+```html
+<lyra-entity-card id="card"></lyra-entity-card>
+<script>
+  document.getElementById('card').entity = {
+    id: 'e1', label: 'Ada Lovelace', type: 'person',
+    description: 'Mathematician', properties: { born: 1815 }, degree: 4,
+  };
+  document.getElementById('card').addEventListener('lyra-entity-activate', (e) => graph.focusNode(e.detail.id));
+</script>
+```
+
+**Known gotchas:**
+- The type badge's data-driven background uses a 10% (not this codebase's usual 16%) quiet-tint mix
+  against `--lyra-color-surface` — the lower percentage is required to hold WCAG AA 4.5:1 text
+  contrast for arbitrary, unvetted type colors.
+
+---
+
+## `lyra-entity-chip`
+
+An inline `@entity` mention for agent prose: flow content, keyboard-focusable, with a hover/focus
+preview popover. The knowledge-graph sibling of `lyra-citation-badge`, reusing its interaction
+contract wholesale. Carries ids through events only — no entity data resolution, no navigation.
+
+**Properties:**
+- `entityId: string = ''` (attribute `entity-id`)
+- `label: string = ''` — the chip's visible text
+- `type: string = ''` (reflected) — lets a host theme per type from CSS, e.g.
+  `lyra-entity-chip[type='person'] { --lyra-entity-chip-color: ... }`
+- `typeLabel?: string` (attribute `type-label`) — optional spoken/visible type qualifier
+
+**Events:** `lyra-entity-activate` (`detail: { id }`, click, or Enter while focused),
+`lyra-entity-open` (`detail: { id }`, dblclick, or Space while focused).
+
+**Slots:** default — rich preview content (typically a compact `lyra-entity-card`), shown in a
+floating popover on hover/focus. No content means no popover and no hover affordance at all.
+
+**CSS parts:** `base` (the clickable `<button>`), `label`, `popover`.
+
+**Themeable custom properties:** `--lyra-entity-chip-color` (default `var(--lyra-color-brand)`,
+text/accent color), `--lyra-entity-chip-bg` (default `var(--lyra-color-brand-quiet)`).
+
+**Optional peer deps:** none.
+
+```html
+<p>…first described by <lyra-entity-chip entity-id="e1" label="Ada Lovelace" type="person">
+  <lyra-entity-card slot=""></lyra-entity-card>
+</lyra-entity-chip>.</p>
+```
+
+**Known gotchas:**
+- Reuses `lyra-citation-badge`'s exact "real preview content" detection (an assigned element with no
+  other `slot`, or non-whitespace text) to decide whether a popover exists at all.
+
+---
+
+## `lyra-neighbor-list`
+
+One entity's relationship rows: relation, direction, neighbor, with per-row navigate and
+expand-in-graph affordances. Never computes neighbors itself (the host derives rows from its own
+graph data) and never mutates a graph.
+
+**Properties:**
+- `rows: LyraNeighborRow[] = []` (attribute: false) — `LyraNeighborRow { relation: string; direction:
+  'in' | 'out' | 'both'; node: LyraEntity }`
+- `groupByRelation: boolean = false` (attribute `group-by-relation`) — inserts a `group-header` row per
+  distinct `relation`
+- `expandable: boolean = false` — renders a per-row expand-in-graph icon button
+- `virtualizeAt: number = 100` (attribute `virtualize-at`) — row count above which the list virtualizes
+- `label: string = ''`
+
+**Events:** `lyra-entity-activate` (`detail: { id }`, a row's node button was activated),
+`lyra-node-expand` (`detail: { id }`, a row's expand button was activated — deliberately the same
+name and detail shape as `lyra-graph`'s own event, so one host handler serves both).
+
+**Slots:** none.
+
+**CSS parts:** `base` (`role="list"`), `group-header` (only when `groupByRelation`), `row`
+(`role="listitem"`), `direction` (`aria-hidden` glyph), `relation`, `node-label`, `node-meta`
+(secondary type/degree text, when present), `expand-button` (only when `expandable`), `empty`
+(shown when `rows` is empty).
+
+**Themeable custom properties:** shared tokens only.
+
+**Optional peer deps:** none.
+
+```html
+<lyra-neighbor-list expandable group-by-relation></lyra-neighbor-list>
+<script>
+  document.querySelector('lyra-neighbor-list').rows = [
+    { relation: 'works_for', direction: 'out', node: { id: 'e2', label: 'Analytical Engine Co.' } },
+  ];
+</script>
+```
+
+**Known gotchas:**
+- `lyra-node-expand`'s detail shape is intentionally identical to `lyra-graph`'s own event of the
+  same name, so a single listener wired to both handles "expand this node's neighborhood" uniformly.
+
+---
+
+## `lyra-path-strip`
+
+A linear node → relation → node chain rendering "why A connects to B" (GraphRAG local-search
+reasoning paths) as a compact, horizontally scrollable strip. One-dimensional and presentational: no
+path finding, no branching, no per-element popovers.
+
+**Properties:**
+- `path: LyraPathElement[] = []` (attribute: false) — a flat alternating sequence:
+  `{ kind: 'node'; node: LyraEntity } | { kind: 'edge'; relation: string; directed?: boolean;
+  reverse?: boolean }`
+- `label: string = ''`
+
+**Events:** `lyra-entity-activate` (`detail: { id }`, a node element activated),
+`lyra-relation-activate` (`detail: { relation, sourceId?, targetId? }`, an edge element activated —
+source/target resolved from the adjacent node elements, `undefined` when the path is malformed at
+that position).
+
+**Slots:** none.
+
+**CSS parts:** `base` (hosts the delegated roving-tabindex keydown handler), `node` (a `<button>`),
+`relation` (a `<button>`), `arrow` (`aria-hidden`, logical — mirrors under RTL), `empty` (shown when
+`path` is empty).
+
+**Themeable custom properties:** shared tokens only.
+
+**Optional peer deps:** none.
+
+```html
+<lyra-path-strip></lyra-path-strip>
+<script>
+  document.querySelector('lyra-path-strip').path = [
+    { kind: 'node', node: { id: 'a', label: 'Ada Lovelace' } },
+    { kind: 'edge', relation: 'wrote', directed: true },
+    { kind: 'node', node: { id: 'b', label: 'Notes on the Analytical Engine' } },
+  ];
+</script>
+```
+
+**Known gotchas:**
+- Purely presentational rendering of a caller-supplied path — it never computes shortest paths or
+  fetches relationship data itself, and never branches (one linear chain per instance).
+
+---
+
+## `lyra-community-card`
+
+A cluster/community summary card (GraphRAG community report): label, LLM summary excerpt, member
+count, member chips with overflow, and a drill-in action. Doesn't own community rendering on the
+graph or membership fetching — `lyra-drill` asks the host to load members/subgraph.
+
+**Properties:**
+- `community: LyraCommunity | null = null` (attribute: false) — `LyraCommunity { id: string; label:
+  string; summary?: string; memberCount?: number }`; `memberCount` is authoritative when it exceeds
+  `members.length`; `null` renders the empty state
+- `members: LyraEntity[] = []` (attribute: false) — rendered as chips, up to `maxMembers`
+- `maxMembers: number = 8` (attribute `max-members`) — remaining members collapse into a "+N"
+  overflow chip
+- `compact: boolean = false` (reflected) — omits the summary excerpt and member chips
+
+**Events:** `lyra-drill` (`detail: { id }`, the drill button, header, or overflow chip — all three
+mean "show me this whole community"), `lyra-entity-activate` (`detail: { id }`, a member chip was
+activated).
+
+**Slots:** `actions` — extra header actions alongside the built-in drill button.
+
+**CSS parts:** `base`, `header`, `title` (`role="heading" aria-level="3"` wrapping a `<button>`),
+`member-count`, `summary` (omitted in `compact`), `members` (omitted in `compact`), `member`,
+`overflow` (the "+N" chip button), `drill-button`, `actions`, `empty` (shown when `community` is
+`null`).
+
+**Themeable custom properties:** shared tokens only.
+
+**Optional peer deps:** none.
+
+```html
+<lyra-community-card></lyra-community-card>
+<script>
+  document.querySelector('lyra-community-card').community = { id: 'c1', label: 'Early computing pioneers', summary: 'A cluster of 19th-century mathematicians and engineers.', memberCount: 12 };
+</script>
+```
+
+**Known gotchas:**
+- `memberCount` (not `members.length`) is the authoritative displayed count whenever it's larger —
+  useful when the host sends only a preview slice of members alongside the real total.
+
+---
+
+## `lyra-chunk-inspector`
+
+A ranked retrieved-chunks list: relevance score bars with tier tones, expandable chunk text, and the
+deep-link event that lands a chunk in `lyra-document-viewer`. Never fetches, ranks, or dedupes; never
+opens documents itself.
+
+**Properties:**
+- `chunks: LyraChunk[] = []` (attribute: false) — `LyraChunk { id: string; text: string; score:
+  number; sourceId: string; title?: string; page?: string | number; anchor?: LyraChunkAnchor }`;
+  `score` is 0–1, `title` falls back to a localized "untitled source", `anchor` (the same
+  discriminated union `lyra-document-viewer.anchor` accepts — page/text-quote/fragment/line-range/
+  cell-range/cfi/time-range/region/node-path) is carried through `lyra-chunk-open` verbatim
+- `thresholds: { high: number; medium: number } = { high: 0.75, medium: 0.5 }` (attribute: false) —
+  score-bar tier cutoffs
+- `sort: 'score' | 'none' = 'score'`
+- `activeId: string = ''` (attribute `active-id`)
+- `virtualizeAt: number = 50` (attribute `virtualize-at`)
+- `compact: boolean = false` (reflected) — hides the text preview/toggle, title/score row only
+- `label: string = ''`
+
+**Events:** `lyra-chunk-open` (`detail: { id, sourceId, anchor? }`, a chunk's title/open button was
+activated — the event a host routes into `lyra-document-viewer`, setting `src` from `sourceId` and
+`anchor` from the chunk's own), `lyra-expand` (`detail: { id, expanded }`, a chunk's text toggle was
+activated).
+
+**Slots:** none.
+
+**CSS parts:** `base` (`role="group"`), `chunk` (`role="listitem"`), `score` (visible percent text),
+`score-bar` (`aria-hidden` track), `score-fill` (tone-mapped fill), `open-button`, `title` (the
+`<span>` inside `open-button` carrying the visible title text), `text` (line-clamped unless
+expanded, omitted when `compact`), `toggle` ("Show more"/"Show less", omitted when `compact`),
+`empty` (shown when `chunks` is empty).
+
+**Themeable custom properties:** shared tokens only.
+
+**Optional peer deps:** none.
+
+```html
+<lyra-chunk-inspector></lyra-chunk-inspector>
+<script>
+  const inspector = document.querySelector('lyra-chunk-inspector');
+  inspector.chunks = [
+    { id: 'c1', text: 'Revenue grew 12% year over year…', score: 0.91, sourceId: 'doc-1', title: 'Q3 report', page: 4 },
+  ];
+  inspector.addEventListener('lyra-chunk-open', (e) => documentViewer.openAt(e.detail.sourceId, e.detail.anchor));
+</script>
+```
+
+**Known gotchas:**
+- `title` and `open-button` are split into two separate parts (rather than one dual-part-name
+  element) because an exact-match `[part="..."]` CSS attribute selector — as this component's own
+  tests use — cannot match a multi-token `part` attribute value.
+
+---
+
+## `lyra-source-picker`
+
+A checkbox tree/list scoping which sources ground the next answer: tri-state folders, select-all,
+type icons, search. **Not `FormAssociated`, deliberately**: this is a scoping panel, not a form
+control — the selection is immediate app state consumed by the next retrieval call, exactly the
+stance `lyra-tool-select-dialog` already takes.
+
+**Properties:**
+- `sources: LyraSourceEntry[] = []` (attribute: false) — `LyraSourceEntry { id: string; label:
+  string; mimeType?: string; name?: string; children?: LyraSourceEntry[] }`; flat (no `children`) or
+  a tree — presence of `children` makes a row a group/folder with tri-state select
+- `selectedIds: string[] = []` (attribute: false) — controlled; the host assigns this back from
+  `lyra-sources-change`
+- `showSelectAll: boolean = true` (attribute `show-select-all`)
+- `searchable: boolean = true`
+- `label: string = ''`
+- `accessibleLabel: string | null = null` (attribute `aria-label`) — overrides the tree's computed
+  accessible name; wins over `label` and the localized default, and attribute-reflects from a
+  host-level `aria-label` so plain markup gets ARIA-name forwarding
+
+**Events:** `lyra-sources-change` (`detail: { selectedIds }`, the complete updated leaf-id array,
+fired after every toggle including select-all).
+
+**Slots:** none.
+
+**CSS parts:** `base`, `search` (the built-in filter `lyra-input`, only when `searchable`),
+`select-all` (only when `showSelectAll`), `summary` ("{selected} of {total} selected"), `tree`
+(`role="tree"`), `item` (`role="treeitem"`), `checkbox` (tri-state glyph), `icon` (the
+`lyra-file-icon` type badge), `label`, `empty` (`noData` when `sources` is empty, `noMatches` when a
+filter empties the tree).
+
+**Themeable custom properties:** shared tokens only.
+
+**Optional peer deps:** none.
+
+```html
+<lyra-source-picker></lyra-source-picker>
+<script>
+  const picker = document.querySelector('lyra-source-picker');
+  picker.sources = [
+    { id: 'folder-1', label: 'Reports', children: [{ id: 'doc-1', label: 'Q3.pdf', mimeType: 'application/pdf' }] },
+  ];
+  picker.addEventListener('lyra-sources-change', (e) => (retrievalScope = e.detail.selectedIds));
+</script>
+```
+
+**Known gotchas:**
+- Deliberately not form-associated — `lyra-sources-change` is the only wiring; there's no
+  `name`/`value`/`FormData` participation the way a genuine form control would have.
+
+---
+
+## `lyra-provenance-panel`
+
+The grounding breakdown for one answer: a sectioned disclosure panel (Entities / Relationships /
+Communities / Text chunks) composing this family's own pieces. The chat ↔ graph ↔ document glue
+component. Pure projection + event conduit: no fetching, no graph/viewer imports, no persistence.
+
+**Properties:**
+- `provenance: LyraProvenance | null = null` (attribute: false) — `LyraProvenance { entities?:
+  LyraEntity[]; relationships?: { path: LyraPathElement[] }[]; communities?: LyraCommunity[]; chunks?:
+  LyraChunk[] }`; each present array renders through the matching sibling component (`lyra-entity-
+  chip` row, one `lyra-path-strip` per relationship, `lyra-community-card`, `lyra-chunk-inspector`);
+  `null` or every section empty renders the overall empty state
+- `types: NodeTypeStyle[] = []` (attribute: false) — forwarded to the Entities section's chips
+- `thresholds: { high: number; medium: number } = { high: 0.75, medium: 0.5 }` (attribute: false) —
+  forwarded to the Text chunks section's `lyra-chunk-inspector`
+- `label: string = ''`
+
+**Events:** `lyra-toggle` (`detail: { section, expanded }`, a section header was toggled —
+`section` is `'entities' | 'relationships' | 'communities' | 'chunks'`).
+
+**Slots:** none.
+
+**CSS parts:** `base`, `section`, `header` (a section's disclosure `<button>`), `count` (a section's
+item-count badge), `body` (`hidden` while collapsed), `empty` (shown when every section is empty).
+
+**Themeable custom properties:** shared tokens only.
+
+**Optional peer deps:** none.
+
+```html
+<lyra-provenance-panel></lyra-provenance-panel>
+<script>
+  document.querySelector('lyra-provenance-panel').provenance = {
+    entities: [{ id: 'e1', label: 'Ada Lovelace', type: 'person' }],
+    chunks: [{ id: 'c1', text: 'Revenue grew 12%…', score: 0.91, sourceId: 'doc-1' }],
+  };
+</script>
+```
+
+**Known gotchas:**
+- Composes `lyra-entity-chip`, `lyra-path-strip`, `lyra-community-card`, and `lyra-chunk-inspector`
+  directly rather than reimplementing their rendering — events from those inner components (e.g.
+  `lyra-entity-activate`, `lyra-chunk-open`) still bubble/compose up through this panel's light DOM
+  for the host to handle in one place.
+
+---
+
+## `lyra-mind-map`
+
+A radial expandable topic tree (NotebookLM Mind Maps): a spatial overview of a topic hierarchy where
+activating a topic drills in or hands the topic to the chat. Hierarchy, not network — no cross-links,
+no force simulation, no communities, no edge labels (that's `lyra-graph`). Zero-dependency SVG; the
+radial layout is closed-form arithmetic, in its own `mind-map-layout.ts` module, mirroring
+`lyra-word-cloud`'s dependency-free precedent.
+
+**Properties:**
+- `topics: LyraTopic[] = []` (attribute: false) — `LyraTopic { id: string; label: string; children?:
+  LyraTopic[] }`; a single root sits at the center, multiple roots hang off an implicit center hub
+- `label: string = ''` — accessible name for the SVG group and the implicit hub's text
+- `expandDepth: number = 1` (attribute `expand-depth`) — initial expansion depth (root + first
+  ring); expansion state afterward is component-managed per topic id and survives `topics`
+  reassignment
+
+**Events:** `lyra-topic-select` (`detail: { id }`, a *leaf* topic was activated),
+`lyra-topic-toggle` (`detail: { id, expanded }`, a parent topic was activated, or auto-expanded by
+keyboard descent).
+
+**Slots:** none.
+
+**CSS parts:** `base`, `svg` (the single-tab-stop focus target), `node`, `node-label`, `link`
+(parent-child connector), `focus-ring` (keyboard focus ring), `live-region` (visually hidden
+announcement region), `empty` (shown when `topics` is empty).
+
+**Themeable custom properties:** `--lyra-mind-map-ring-gap` (default `6rem`, radius step per depth
+ring).
+
+**Optional peer deps:** none.
+
+```html
+<lyra-mind-map style="height:480px" expand-depth="2"></lyra-mind-map>
+<script>
+  document.querySelector('lyra-mind-map').topics = [
+    { id: 'root', label: 'Computing history', children: [
+      { id: 'people', label: 'People', children: [{ id: 'ada', label: 'Ada Lovelace' }] },
+      { id: 'machines', label: 'Machines' },
+    ] },
+  ];
+</script>
+```
+
+**Known gotchas:**
+- A user's explicit expand/collapse only ever overrides the `depth < expandDepth` default in the
+  direction chosen — reassigning `topics` (even with the same ids) never silently discards that
+  override.
+- Node-position transitions use `--lyra-transition-base`, which already collapses to near-zero under
+  `prefers-reduced-motion: reduce` globally, so expansion snaps rather than tweening for a
+  reduced-motion user with no extra branching in this component.
+
+---
+
 # Chart family (`chart/`)
 
 ## `lyra-chart` (core)
@@ -2753,6 +3746,12 @@ Chart.js wrapper every other `lyra-*-chart` tag subclasses; supports both a simp
   noTooltip?: boolean; axis?: 'y'|'y2'; pointColors?: string[]; pointRadius?: number; type?:
   'line'|'bar' }`
 - `legend: boolean = false`
+- `legendPosition: LyraChartLegendPosition = 'top'` (attribute `legend-position`) — places the
+  legend at `top`, `right`, `bottom`, or `left`; `auto` chooses right above 480px and bottom below
+  that allocation width
+- `valueFormatter?: LyraChartValueFormatter` (attribute: false) — formats numeric tick, tooltip,
+  and legend values; the callback receives the value and `'tick'`, `'tooltip'`, or `'legend'`
+  context
 - `area: boolean = false`
 - `zoom: boolean = false`
 - `height: string = '280px'`
@@ -2774,6 +3773,9 @@ Chart.js wrapper every other `lyra-*-chart` tag subclasses; supports both a simp
   localized data/trend summary
 - `showDataTable: boolean = false` (attribute `show-data-table`) — makes the always-available
   accessible data table visible rather than screen-reader-only
+- `chartArea: LyraChartArea | undefined` (readonly) — current Chart.js chart-area geometry in
+  canvas-local coordinates (`top`, `left`, `right`, `bottom`, `width`, `height`), when a chart is
+  drawn
 
 **Methods:** `resetZoom()` (reset any active zoom/pan to the original view), `refreshTheme()`
 (forces a redraw so the `--lyra-chart-*` tokens below are re-read from the current computed style —
@@ -2785,9 +3787,11 @@ the escape hatch for a consumer's own theme-toggle handler to call when it flips
 a data point/segment, for any chart type, not just bar; `detail: { datasetIndex: number, index:
 number, label: string | undefined, value: unknown }`)
 
-**Slots:** `data-table` — an optional consumer-provided accessible table alternative.
+**Slots:** `data-table` — an optional consumer-provided accessible table alternative; `center` —
+optional overlay content positioned at the chart area's center, useful for doughnut and pie totals.
 
-**CSS parts:** `base`, `canvas`, `reset-zoom-button`, `description`, `data-table`
+**CSS parts:** `base`, `canvas`, `reset-zoom-button`, `description`, `data-table`, `center` (the
+chart-area-centered wrapper for the `center` slot)
 
 **Themeable custom properties:** `--lyra-chart-height` (set programmatically on the host from the
 `height` property — must be read from the host, not a shadow-tree descendant, since custom
@@ -2902,6 +3906,10 @@ passthrough). Not a subclass of `LyraChart`.
 - `pointText?: (label: string, value: number, datasetIndex: number) => string` (attribute: false) —
   overrides the per-bar/per-point `<title>`/`aria-label` tooltip text (mirrors `lyra-heatmap`'s
   `cellText`). Falls back to the built-in raw-value template when unset.
+- `legendText?: (label: string, datasetIndex: number) => string` (attribute: false) — appends
+  formatter-supplied text (e.g. a value or percentage share) after each series' label in the
+  built-in legend row, mirroring `pointText`/`tickFormat`'s opt-in-hook convention. Falls back to
+  the label alone when unset; no-op while `legend` is `false`.
 - `roundedBars: boolean = false` (attribute `rounded-bars`, bar type only) — draws each bar as a
   rounded-top-corner shape instead of a square-cornered `<rect>`.
 - `skipZero: boolean = false` (attribute `skip-zero`, bar type only) — omits a bar entirely (no
@@ -2944,8 +3952,9 @@ fresh, small SVG render is cheaper and more correct than a lossy cache.
 
 **CSS parts:** `base`, `grid-line`, `axis-label`, `axis-title`, `bar` (each bar rect; carries
 `data-selected` when its category index is in `selectedIndex`), `line`, `point`, `legend`,
-`legend-item`, `legend-swatch`, `live-region` (the current mark announcement for keyboard users),
-`data-list` (a visually hidden list of all plotted data points).
+`legend-item`, `legend-swatch`, `legend-text` (extra per-item text after the series label,
+rendered only when `legendText` is set), `live-region` (the current mark announcement for keyboard
+users), `data-list` (a visually hidden list of all plotted data points).
 
 **Themeable custom properties:** `--lyra-chart-height` (same host-level property as `lyra-chart`);
 `--lyra-chart-grid-color`, `--lyra-chart-tick-color`, `--lyra-chart-legend-color` — same token
@@ -3105,8 +4114,8 @@ independently of the base `chart-loader.ts`).
 
 ## `lyra-map`
 
-A `maplibre-gl` wrapper with a declarative legend and a single choropleth GeoJSON fill layer, plus a
-raw `map` escape hatch for anything unexposed.
+A `maplibre-gl` wrapper with a declarative legend, a single choropleth GeoJSON fill layer, markers,
+and additive plain-GeoJSON `dataLayers`, plus a raw `map` escape hatch for anything unexposed.
 
 **Properties:**
 - `center: [number, number] = [0, 0]`
@@ -3131,6 +4140,17 @@ raw `map` escape hatch for anything unexposed.
   escaped) when the content is plain text. A marker whose `color` changes for a persisting `id`
   can't be recolored in place (no `Marker.setColor()`) and is torn down/reconstructed instead — see
   gotchas.
+- `dataLayers: GeoJsonDataLayer[] = []` (attribute: false) — `GeoJsonDataLayer { sourceId: string;
+  geojson: GeoJSON.Feature | GeoJSON.FeatureCollection; tone?: 'accent' | 'success' | 'warning' |
+  'danger' | 'neutral' }`. Each entry adds one GeoJSON source plus three layers
+  (`${sourceId}-fill`/`${sourceId}-line`/`${sourceId}-circle`, filtered by geometry type so a mixed
+  `FeatureCollection` renders correctly across all three), colored from the matching `--lyra-color-*`
+  token (`tone` defaults to `'accent'` → `--lyra-color-brand`). Independent of `choropleth` — no
+  `field`/`stops` color-interpolation, just the geometry rendered in a flat tone; use `choropleth`
+  instead when you need a data-driven color ramp. Reconciled by `sourceId` the same way `choropleth`
+  is: an entry whose `sourceId` persists across a `dataLayers` reassignment gets its GeoJSON updated
+  in place (`setData()`), one that's dropped has its source/layers removed, and a genuinely new
+  `sourceId` gets a new source/layers — nothing leaks on removal, style change, or disconnect.
 - `label: string = ''` — accessible name for the map region, applied as `[part="base"]`'s
   `aria-label`. A plain `aria-label` attribute on the host itself is honored as a fallback when
   `label` is left unset, matching `lyra-slider`/`lyra-checkbox`/`lyra-switch`; with neither set, it
@@ -3175,9 +4195,9 @@ exists and was hit)
   `removeSource` on whatever was previously applied before adding the new one (or nothing, if
   cleared).
 - `mapStyle` changes after construction now call `setStyle()` (in addition to `center`/`zoom`
-  already calling `setCenter`/`setZoom`) — the choropleth is automatically re-applied once the new
-  style's own `'style.load'` fires, since a style change wipes every layer/source maplibre-gl knows
-  about.
+  already calling `setCenter`/`setZoom`) — the choropleth and `dataLayers` are both automatically
+  re-applied once the new style's own `'style.load'` fires, since a style change wipes every
+  layer/source maplibre-gl knows about.
 - Point markers now have a declarative API (`markers`, above) with popup support — the `.map` escape
   hatch and manual `new maplibregl.Marker()` are no longer the only way to place pins.
 - a marker whose `color` changes for a persisting `id` is torn down and reconstructed (maplibre-gl's
@@ -3698,6 +4718,9 @@ wrapper at all, so existing text-only tabs are unaffected.
 - `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`)
+- `accessibleLabel: string | null = null` (attribute `aria-label`) — accessible name applied to the
+  `role="tablist"` strip; attribute-reflects from a host-level `aria-label`. Unset, the tablist
+  renders without an `aria-label` (there is no localized default name).
 
 **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
@@ -3760,6 +4783,9 @@ convention).
 - `orientation: 'horizontal' | 'vertical' = 'horizontal'` (reflected) — `'horizontal'` (the default)
   lays steps out in a row (Left/Right, RTL-aware, navigate); `'vertical'` stacks them (Up/Down
   navigate instead, no RTL swap needed).
+- `accessibleLabel: string | null = null` (attribute `aria-label`) — accessible name applied to the
+  `role="tablist"` step strip; attribute-reflects from a host-level `aria-label`. Unset, the
+  tablist renders without an `aria-label` (there is no localized default name).
 
 **Events:** `lyra-step-select` (`detail: { index, id }`) — fired on click, or Enter/Space while
 focused, on a non-`disabled` step. Cancelable, though this component takes no default action of its
@@ -3860,6 +4886,66 @@ keyboard.
 
 ---
 
+## `lyra-swatch-picker`
+
+A single-select picker over a small, fixed set of color swatches with the WAI-ARIA APG
+`radiogroup` contract built in: `role="radiogroup"`/`role="radio"`, roving tabindex, automatic
+activation (click or arrow-key move both select immediately, like a native radio group), cyclic
+Arrow/Home/End navigation. First-party invention (no Web Awesome equivalent). Distinct from
+`lyra-color-picker`'s freeform native color input — this picks exactly one of N designer-chosen
+named colors, the shape apps otherwise hand-roll as a row of round accent-color buttons.
+
+**Properties:**
+- `options: SwatchOption[] = []` (attribute: false) — `SwatchOption { value: string; color: string;
+  label: string }`; `color` is any CSS color string used as the swatch fill, `label` is each
+  swatch's accessible name and `title`.
+- `value: string | null = null` — the currently selected option's `value` (controlled); `null`
+  leaves nothing selected while keeping the first swatch tabbable.
+- `label: string = ''` — accessible name copied to the internal `role="radiogroup"`; when empty, a
+  host-level `aria-label` is used as a fallback.
+
+**Events:** `lyra-change` (`detail: { value }`) — fired only when the selected value actually
+changes via click or keyboard (re-selecting the current swatch is a no-op).
+
+**Slots:** none.
+
+**CSS parts:** `base` (the `role="radiogroup"` root), `swatch` (a single `role="radio"` color
+swatch; the selected one is `[part='swatch'][aria-checked='true']`).
+
+**Themeable custom properties:** `--lyra-swatch-picker-selected-color` (ring color around the
+selected swatch, defaults to `--lyra-color-brand`, themeable independently of the focus ring); plus
+shared tokens — `--lyra-color-border`/`-brand`, `--lyra-space-xs`, `--lyra-size-1-5rem`,
+`--lyra-border-width-thin`/`-thick`, `--lyra-radius`, `--lyra-transition-fast`,
+`--lyra-focus-ring-*`.
+
+**Optional peer deps:** none.
+
+```html
+<lyra-swatch-picker label="Accent color"></lyra-swatch-picker>
+<script type="module">
+  const picker = document.querySelector('lyra-swatch-picker');
+  picker.options = [
+    { value: 'blue', color: '#0969da', label: 'Blue' },
+    { value: 'green', color: '#1a7f37', label: 'Green' },
+    { value: 'purple', color: '#8250df', label: 'Purple' },
+  ];
+  picker.value = 'green';
+  picker.addEventListener('lyra-change', (e) => console.log(e.detail.value));
+</script>
+```
+
+**Known gotchas:**
+- arrow-key navigation cycles (past the last swatch wraps to the first, and vice versa) rather than
+  clamping, and self-selects on move — arrow-navigating to a swatch immediately updates `value` and
+  fires `lyra-change`, there's no separate commit step.
+- under RTL (nearest `dir="rtl"` ancestor) `ArrowLeft`/`ArrowRight` swap which direction they move.
+- each swatch's fill comes from its option's `color`, applied through a per-swatch custom property
+  so a consumer's `::part(swatch)` `background-color` rule can still override it.
+- the semantic `radiogroup` lives inside shadow DOM. Set `label` (preferred for reactive code) or a
+  host `aria-label`; the component deliberately forwards the resulting name to that internal role.
+
+---
+
 ## `lyra-checkbox`
 
 A boolean form control. `role="checkbox"` with an `aria-checked` that can also be `"mixed"`, and a
@@ -4020,22 +5106,32 @@ stack overflow on cyclic `data`.
 - `search: string = ''` — case-insensitive substring match against keys/values; matches are
   highlighted and their ancestors auto-expanded
 
+**Methods:** `runSearch(query)` sets the declarative `search` property and awaits the recompute,
+resolving the match count — named distinctly from `search` because a class member can't share a name
+with a reactive property. `searchNext()`/`searchPrevious()` advance/step back a match cursor
+(wrapping) and scroll the active match into view, resolving `false` when there are no matches.
+`clearSearch()` resets `search` to `''`, clearing all matches and the cursor.
+
 **Events:** `lyra-copy` (`detail: { text: string }`) — fired by the top-level copy button or a
 per-node one. Fires even when `navigator.clipboard` is unavailable or the write silently failed
 (a rejected `writeText()` is swallowed), so a consumer can still observe copy *intent* — the event
 is not a confirmation that the OS clipboard was actually reached. Copying a circular `data` value
 serializes safely, substituting the same `Circular reference` marker the tree view renders, instead
-of throwing.
+of throwing. `lyra-search-change` (`detail: { query, matchCount, activeIndex }`) — fired whenever the
+search query, match count, or active-match cursor changes, from `runSearch()`/`searchNext()`/
+`searchPrevious()`/`clearSearch()`, or a direct `search`/`data` property write.
 
 **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, `data-match` while it matches `search`),
+tree), `key` (an object property key or array index label, `data-match` while it matches `search`,
+`data-active` while it is the current `searchNext()`/`searchPrevious()` cursor position),
 `value` (a primitive value's text — carries `data-type` of
-`string`/`number`/`boolean`/`null`/`undefined`/`circular` 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),
+`string`/`number`/`boolean`/`null`/`undefined`/`circular` for per-type coloring, `data-match`
+while it matches `search`, and `data-active` while it is the current cursor position), `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` (aria-label "Copy JSON to
 clipboard") or a per-node one (aria-label `Copy ${key/type}`, e.g. "Copy age"); only rendered when
 `copyable`)
@@ -4180,6 +5276,15 @@ instance on a page shares one load. `heading`/`code`/`blockquote`/`table`/`link`
 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).
 
+Fenced code blocks are also syntax-highlighted via the same optional `shiki` peer `<lyra-code-block>`
+uses, gated by `highlightCode` (default `true`). This is a pure upgrade, not a separate opt-in: it's
+already transparently gated by whether `shiki` is installed at all, so an app that never installs the
+peer sees byte-identical output to before this property existed. The very first render of any content
+is always plain text/code (identical to today's output); highlighting arrives as an asynchronous
+upgrade one render later once shiki resolves and the block's language is tokenized. No highlighting
+is attempted while `streaming` is `true` — it applies once a stream settles, adding no per-chunk cost
+while content is still arriving.
+
 **Properties:**
 - `content: string = ''` — the Markdown source to render
 - `sanitize: boolean = true` — sanitize `marked`'s HTML output with DOMPurify before rendering
@@ -4214,6 +5319,27 @@ produced HTML in a single pass (no second DOM walk after insertion).
 - `streaming: boolean = false` (reflected) — marks the host `aria-busy="true"` while partial Markdown
   is still arriving and lets consumers target `lyra-markdown[streaming]`; busy state also remains
   true while parser dependencies are loading
+- `highlightCode: boolean = true` (attribute `highlight-code`) — syntax-highlights fenced code
+  blocks via the optional `shiki` peer. `true` (the default) upgrades every fenced block once the
+  peer is available; set `false` to keep plain output even when `shiki` is installed. No effect
+  while `streaming` is `true`
+- `languages?: Record<string, ShikiLanguageInput>` (attribute: false) — same shape and purpose as
+  `<lyra-code-block>`'s own `languages`: a fine-grained, explicit language-grammar bundle scoping
+  shiki's build output to just those grammars instead of its full ~200-language bundle. Forwarded
+  verbatim to `loadShikiHighlighterCore()`. Unset (the default) uses the default full-bundle loader
+- `languagesOnly: boolean = false` (attribute `languages-only`) — same purpose as
+  `<lyra-code-block>`'s own `languagesOnly`: skips the default full-bundle loader entirely, so a
+  fenced block whose language isn't in `languages` falls back to plain unhighlighted text rather
+  than reaching for the full bundle. No effect unless `languages` is also set
+- `headingAnchors: boolean = false` (attribute `heading-anchors`) — stamps a computed
+  GitHub-slugger-style slug as `id` on every rendered heading.
+- `math: boolean = false` — renders `$inline$` and `$$block$$` TeX via the optional `katex` peer,
+  lazy-loaded the same way as `marked`/`dompurify`/`shiki`.
+- `anchorKinds: readonly ('fragment' | 'text-quote')[]` (readonly) — the anchor kinds this
+  component resolves for the shared anchor-target contract.
+
+**Methods:** `getHeadingTree()` returns the document-ordered heading outline (`{ level, text, slug
+}[]`) computed on every parse, regardless of `headingAnchors`.
 
 **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
@@ -4238,7 +5364,10 @@ Menlo, Consolas, monospace` — the code/code-block font; component-specific sin
 **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.
+`sanitize="false"` (so `dompurify` is never needed) is a valid, supported combination. Also `shiki`,
+the same optional peer `<lyra-code-block>` uses, for `highlightCode`'s fenced-block syntax
+highlighting — independent of the `marked`/`dompurify` pair, and its absence never blocks rendering
+(fenced blocks simply stay unhighlighted).
 
 ```html
 <lyra-markdown
@@ -4315,6 +5444,10 @@ conversation-surface level).
   rendered) — mirrors `lyra-widget`'s identical `collapsible`/`collapsed` pair
 - `attachmentsPosition: 'before'|'after' = 'after'` (attribute `attachments-position`) — places the
   `attachments` slot before or after the message body; both the visual and reading order follow it
+- `actionsOutsideBubble: boolean = false` (attribute `actions-outside-bubble`, reflected) — renders
+  the `actions` slot's content as a sibling immediately after `[part="bubble"]` instead of nested
+  inside `[part="footer"]`'s own padding/background box, for a consumer whose action row (e.g. a
+  hover-reveal copy button) must sit visually outside the bubble's chrome
 
 **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
@@ -4330,6 +5463,8 @@ attachment chips, rendered below the message body)
 `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`
+(rendered inside the footer by default; a sibling immediately after `bubble` when
+`actionsOutsideBubble` is set)
 
 **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
@@ -5235,6 +6370,15 @@ invention (no Web Awesome equivalent).
 - `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.
+- `itemRole: 'listitem' | 'row' = 'listitem'` (attribute `item-role`) — `'listitem'` (default)
+  preserves the plain `role="list"`/`role="listitem"` mapping with `aria-setsize`/`aria-posinset`.
+  `'row'` additionally maps `[part="base"]` to `role="rowgroup"`, `[part="spacer"]` to
+  `role="presentation"`, and each row to `role="row"` with `aria-rowindex` instead — for a consumer
+  composing its own `role="table"` wrapper and header row around this component (see
+  `lyra-dataset-viewer`).
+- `rowIndexOffset: number = 0` (attribute `row-index-offset`) — added to a row's 1-based index to
+  compute `aria-rowindex` in `item-role="row"` mode (e.g. `1` when a consumer renders its own header
+  row occupying `aria-rowindex="1"` outside this component). No effect in `'listitem'` mode.
 - `overscan: number = 6` — extra rows rendered beyond the visible viewport on each side; finite
   values are floored and clamped to 0–100, while non-finite values use the default 6, so an invalid
   runtime value cannot disable windowing and render the entire collection.
@@ -5254,6 +6398,12 @@ The package root also exports `groupByRecency(items, options?)`, a DOM-free help
 non-empty Today/Yesterday/Previous 7 Days/Older buckets, preserves input order within each bucket,
 and accepts a timestamp extractor, reference date, and label overrides.
 
+**Methods:** `scrollToIndex(index, options?)` — the programmatic counterpart to `active-id`'s
+automatic scroll-into-view, for a host that needs to scroll to a specific row without changing which
+row is "active." `options.align` is `'start'`, `'end'`, or `'auto'` (default — no scroll at all when
+already fully visible); `options.behavior` (default `'smooth'`) is forced to `'auto'` under
+`prefers-reduced-motion: reduce`. `index` is clamped to `0…items.length-1`.
+
 **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
@@ -5262,10 +6412,12 @@ current visible, non-overscanned item index range — fired only when it actuall
 
 **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"`), `group` (a `groups` entry's positioned
-`role="heading"` marker)
+**CSS parts:** `base` (the scrollable container, `role="list"` — or `role="rowgroup"` in
+`item-role="row"` mode — `tabindex="0"`), `spacer` (the full-content-height inner element
+establishing true scroll extent; `role="presentation"` in `item-role="row"` mode), `row` (one
+rendered row's absolutely-positioned wrapper, `role="listitem"` — or `role="row"` with
+`aria-rowindex` in `item-role="row"` mode), `group` (a `groups` entry's positioned `role="heading"`
+marker)
 
 **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),
@@ -6685,6 +7837,19 @@ and it's what every instance renders at zero extra bytes until shiki resolves.
   code scrolls internally past this height instead of growing the page
 - `lineNumbers: boolean = false` (attribute `line-numbers`, reflected) — displays one-based line
   numbers for both highlighted output and the plain-text fallback
+- `highlightLines: string = ''` (attribute `highlight-lines`) — comma-separated 1-based inclusive
+  line ranges (e.g. `"3-5,7"`) to visually emphasize. Declarative sugar over `highlights` — merges
+  with, and renders identically to, any `line-range` entries there.
+- `interactiveLines: boolean = false` (attribute `interactive-lines`) — turns the
+  (`lineNumbers`-gated) gutter into a roving-tabindex group of buttons emitting `lyra-line-click`.
+  Has no effect while `lineNumbers` is unset.
+- `highlights: LyraHighlight[] = []` (attribute: false) — host-supplied highlights to paint over the
+  code (the shared anchor-target `LyraHighlight` contract from `document-viewer/anchors.ts`). Only
+  `line-range` anchors are meaningful here — every other `LyraAnchor` kind is ignored.
+- `activeHighlightId: string | null = null` (attribute `active-highlight-id`) — the `highlights`
+  entry, if any, currently treated as active (`data-active` on its lines).
+- `anchorKinds: LyraAnchor['kind'][]` — readonly `['line-range']`, for the shared anchor-target
+  contract.
 - `languages?: Record<string, ShikiLanguageInput>` (attribute: false) — a map of language id to an
   already-imported shiki grammar module (e.g. `{ bash: bashGrammar }` from a module-scope
   `import bash from 'shiki/langs/bash.mjs'`). When `language` matches a key here, highlighting is
@@ -6696,15 +7861,26 @@ and it's what every instance renders at zero extra bytes until shiki resolves.
 - `languagesOnly: boolean = false` (attribute `languages-only`) — skips the default shiki loader;
   use when every requested language is supplied through `languages`
 
+**Methods:** `scrollToAnchor(target)` — resolves a `line-range` anchor (or a `highlights` id string
+resolving to one) by scrolling its start line into view within `[part="body"]`; resolves `false`
+when the anchor isn't a `line-range`, the id isn't found, or the start line is out of bounds.
+
 **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),
 `lyra-toggle` (`detail: { collapsed: boolean }` — fired when the built-in collapse/expand header
-button is activated, same event name/shape convention as `<lyra-thinking-panel>`'s own `lyra-toggle`)
+button is activated, same event name/shape convention as `<lyra-thinking-panel>`'s own `lyra-toggle`),
+`lyra-line-click` (`detail: { line: number }` — a gutter line number was activated while
+`interactiveLines` is set), `lyra-highlight-activate` (`detail: { id: string }` — declared for
+parity with this library's other anchor-target viewers; not currently emitted by this component),
+`lyra-text-select` (`detail: { text, anchor, rects }` — a text selection inside the code body ended;
+`anchor` is a `line-range` anchor covering the selected lines)
 
 **Slots:** none.
 
 **CSS parts:** `base`, `header`, `filename`, `language`, `copy-button`, `toggle`, `body`, `pre`,
-`code`
+`code`, `line-highlight` (a line marked by `highlightLines` or a `line-range` entry in `highlights`),
+`line-button` (a gutter line-number button, only rendered while `interactiveLines` and `lineNumbers`
+are both set)
 
 **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
@@ -6802,19 +7978,40 @@ toggle, the loading-skeleton behavior while the fine-grained highlighter resolve
   code scrolls internally past this height instead of growing the page.
 - `lineNumbers: boolean = false` (attribute `line-numbers`, reflected) — displays one-based line
   numbers for highlighted and plain output.
+- `highlightLines: string = ''` (attribute `highlight-lines`) — comma-separated 1-based inclusive
+  line ranges (e.g. `"3-5,7"`) to visually emphasize. Declarative sugar over `highlights` — merges
+  with, and renders identically to, any `line-range` entries there.
+- `interactiveLines: boolean = false` (attribute `interactive-lines`) — turns the
+  (`lineNumbers`-gated) gutter into a roving-tabindex group of buttons emitting `lyra-line-click`.
+  Has no effect while `lineNumbers` is unset.
+- `highlights: LyraHighlight[] = []` (attribute: false) — host-supplied highlights to paint over the
+  code. Only `line-range` anchors are meaningful here — every other `LyraAnchor` kind is ignored.
+- `activeHighlightId: string | null = null` (attribute `active-highlight-id`) — the `highlights`
+  entry, if any, currently treated as active (`data-active` on its lines).
+- `anchorKinds: LyraAnchor['kind'][]` — readonly `['line-range']`, for the shared anchor-target
+  contract, identical to `<lyra-code-block>`.
 - `languages: Record<string, ShikiLanguageInput> = {}` (attribute: false) — grammar definitions this
   instance can highlight, e.g. `{ json: jsonGrammar }` (import from `shiki/langs/<name>.mjs`). Empty
   (the default) never highlights at all — every `language` renders the plain-text fallback.
 
+**Methods:** `scrollToAnchor(target)` — resolves a `line-range` anchor (or a `highlights` id string
+resolving to one) by scrolling its start line into view within `[part="body"]`; resolves `false`
+when the anchor isn't a `line-range`, the id isn't found, or the start line is out of bounds.
+Identical behavior to `<lyra-code-block>`'s own method.
+
 **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),
 `lyra-toggle` (`detail: { collapsed: boolean }` — fired when the built-in collapse/expand header
-button is activated).
+button is activated), `lyra-line-click` (`detail: { line: number }` — a gutter line number was
+activated while `interactiveLines` is set), `lyra-highlight-activate` (`detail: { id: string }` —
+declared for parity with this library's other anchor-target viewers; not currently emitted by this
+component), `lyra-text-select` (`detail: { text, anchor, rects }` — a text selection inside the code
+body ended; `anchor` is a `line-range` anchor covering the selected lines).
 
 **Slots:** none.
 
 **CSS parts:** `base`, `header`, `filename`, `language`, `copy-button`, `toggle`, `body`, `pre`,
-`code` — identical set to `<lyra-code-block>`.
+`code`, `line-highlight`, `line-button` — identical set to `<lyra-code-block>`.
 
 **Themeable custom properties:** identical to `<lyra-code-block>` — `--lyra-code-block-max-height`,
 `--lyra-code-block-font`, plus the same shared tokens.
@@ -6861,6 +8058,15 @@ First-party invention (no Web Awesome equivalent).
   all-removals diff of `oldText`.
 - `copyable: boolean = false` — shows a copy-to-clipboard button for the full unified-diff text.
   `false` (the default) renders no button.
+- `layout: 'unified' | 'split' = 'unified'` (reflected) — `'unified'` (the default) renders today's
+  single interleaved `<pre>`; `'split'` renders two side-by-side `[part="side"]` columns derived from
+  the same diff alignment.
+- `language: string = ''` — a shiki-recognized language id. Highlighting activates only when this
+  has a matching entry in `languages` — there is deliberately no default full-table
+  `lyra-code-block`-style fallback, so this component never reaches shiki's ~200-language
+  dynamic-import table.
+- `languages?: Record<string, ShikiLanguageInput>` (attribute: false) — grammar definitions this
+  instance can highlight, same shape as `lyra-code-block-core`'s own `languages`.
 
 **Events:** `lyra-copy` (`detail: { text: string }` — the full unified-diff text, fired on
 copy-button activation regardless of whether the clipboard write actually succeeded).
@@ -6868,15 +8074,19 @@ copy-button activation regardless of whether the clipboard write actually succee
 **Slots:** none.
 
 **CSS parts:** `base` (the root wrapper), `line` (a single line; carries
-`data-type="equal"|"add"|"remove"`), `copy-button` (the copy affordance, only rendered while
-`copyable`).
+`data-type="equal"|"add"|"remove"|"empty"` — `"empty"` is an unbalanced-replace placeholder cell in
+`layout="split"` and never carries a `+`/`-` prefix), `copy-button` (the copy affordance, only
+rendered while `copyable`), `side` (one column in `layout="split"`, `data-side="old"|"new"`).
 
 **Themeable custom properties:** `--lyra-diff-view-font` (default `var(--lyra-font-mono)`), plus
 shared tokens `--lyra-color-border`/`-surface`/`-success`/`-success-quiet`/`-danger`/
 `-danger-quiet`/`-text`, `--lyra-radius`, `--lyra-space-xs`/`-s`, `--lyra-font-size-sm`,
 `--lyra-line-height-snug`, `--lyra-focus-ring-*`.
 
-**Optional peer deps:** none.
+**Optional peer deps:** `shiki` (the same fine-grained `shiki/core`/`shiki/engine/oniguruma`/
+`shiki/wasm` subset `lyra-code-block-core` uses, never `shiki`'s full ~200-language main entry point)
+— only loaded once both `language` and a matching `languages` entry are set; unset/unmatched leaves
+the plain unhighlighted diff text untouched.
 
 ```html
 <lyra-diff-view copyable></lyra-diff-view>
@@ -6904,6 +8114,72 @@ consumer can compute or unit-test the same alignment without instantiating the e
 
 ---
 
+## `lyra-stack-trace`
+
+Parses common V8/JS-TS, Firefox/Safari, and Python stack traces into a leading message plus
+activatable frames, splitting chained/caused-by errors (`Caused by:`, `[cause]:`, Python's "direct
+cause"/"During handling" separators) into separate groups. Frames matching `internalPatterns` fold
+behind a count-labeled toggle. Falls back to verbatim raw text when nothing parses. First-party
+invention (no Web Awesome equivalent).
+
+**Properties:**
+- `trace: string = ''` — the raw stack trace text to parse and render.
+- `collapseInternal: boolean = true` (attribute: `collapse-internal`) — folds runs of internal
+  frames behind a toggle.
+- `internalPatterns: (string | RegExp)[] = DEFAULT_INTERNAL_PATTERNS` (attribute: false) —
+  file-path substrings/`RegExp`s that mark a frame as internal.
+- `copyable: boolean = true` — shows a copy-to-clipboard button for the raw trace text.
+- `maxHeight: string = ''` (attribute: `max-height`) — caps the rendered block size and enables an
+  internal scrollbar once content exceeds it (any valid CSS length). Empty string (the default)
+  grows with content.
+
+**Events:**
+- `lyra-frame-select` (`detail: { file?: string; line?: number; column?: number; raw: string }`) —
+  a frame was activated. `column` is always undefined for Python frames, which carry no column
+  information.
+- `lyra-copy` (`detail: { text: string }`) — the raw, unparsed trace text, fired on copy-button
+  activation regardless of whether the clipboard write actually succeeded.
+
+**Slots:** none.
+
+**CSS parts:** `base` (the root wrapper; respects `max-height`), `message` (the leading error
+message text for a group), `group` (one chained-error group of frames), `frame` (a single frame
+button; carries `data-internal` for internal frames), `frame-function` (the frame's function
+name), `frame-location` (the frame's `file:line:col` text), `internal-toggle` (the collapse/expand
+toggle for a run of internal frames), `raw` (the verbatim fallback when zero structured frames
+parsed), `copy-button` (only rendered while `copyable`).
+
+**Themeable custom properties:** `--lyra-stack-trace-max-height` (default `none`),
+`--lyra-stack-trace-font` (default `var(--lyra-font-mono)`), plus shared tokens
+`--lyra-color-border`/`-surface`/`-text`/`-text-quiet`/`-brand`, `--lyra-radius`,
+`--lyra-border-width-thin`, `--lyra-space-xs`/`-s`/`-2xs`, `--lyra-font-size-sm`/`-xs`,
+`--lyra-font-weight-bold`/`-semibold`, `--lyra-focus-ring-*`.
+
+**Optional peer deps:** none.
+
+```html
+<lyra-stack-trace></lyra-stack-trace>
+<script type="module">
+  const stackTrace = document.querySelector('lyra-stack-trace');
+  stackTrace.trace = 'TypeError: boom\n    at doThing (/app/src/util.js:10:5)';
+  stackTrace.addEventListener('lyra-frame-select', (e) => console.log(e.detail.file, e.detail.line));
+</script>
+```
+
+The package root also exports the pure `parseStackTrace(trace: string, internalPatterns: (string |
+RegExp)[]): StackGroup[]` helper (plus `DEFAULT_INTERNAL_PATTERNS`, and the `StackFrame`/
+`StackGroup` types) — the same parsing function this component's own `willUpdate()` calls, exposed
+standalone so a consumer can parse or unit-test traces without instantiating the element at all.
+
+**Known gotchas:**
+- an internal-frame run only collapses behind the `internal-toggle` when it is two or more
+  consecutive internal frames; a single isolated internal frame renders as a normal `frame` button
+  (there is nothing useful to fold).
+- when `trace` doesn't match any of the supported formats, `parseStackTrace()` returns `[]` and the
+  component renders the text verbatim in a `raw` part instead of silently dropping content.
+
+---
+
 ## `lyra-tool-approval-dialog`
 
 A human-in-the-loop gate: presents one proposed tool/function call (`toolName` + `args`) and blocks an
@@ -7553,8 +8829,9 @@ used" summary.
 
 **Properties:**
 - `segments: ContextMeterSegment[] = []` (attribute: false, JS-only) — `{ label: string; value:
-  number; tone?: 'brand' | 'success' | 'warning' | 'danger' | 'neutral' }[]`. `value` is an *absolute*
+  number; tone?: 'brand' | 'success' | 'warning' | 'danger' | 'neutral'; color?: string }[]`. `value` is an *absolute*
   quantity measured against `total`, never a pre-computed percentage.
+  `color`, when supplied, is a sanitized arbitrary CSS color that takes precedence over `tone`.
 - `total: number = 0` — the full capacity segments are measured against (e.g. a model's context
   window size).
 - `variant: 'ring' | 'bar' = 'bar'` (reflected)
@@ -7569,9 +8846,11 @@ A host `aria-label` overrides the generated meter summary and is preserved acros
 **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`
+capacity), `segment` (one occupied segment — carries `data-tone` and, for custom colors,
+`--lyra-context-meter-segment-color`), `label`
 
-**Themeable custom properties:** no component-specific custom properties; consumes shared tokens
+**Themeable custom properties:** `--lyra-context-meter-segment-color` is set per segment when its
+`color` field is supplied; otherwise the component consumes shared tokens
 `--lyra-space-xs`, `--lyra-color-text-quiet`, `--lyra-font`, `--lyra-radius`, `--lyra-color-border`,
 `--lyra-color-surface` (the bar variant's inter-segment seam), `--lyra-color-brand`,
 `--lyra-color-success`, `--lyra-color-warning`, `--lyra-color-danger`, `--lyra-transition-base`.
@@ -7774,6 +9053,20 @@ image path — and the generic fallback simply omits `[part="download-link"]` en
 - `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.
+- `zoomable: boolean = false` (reflected) — wraps the rendered image (image format only) in an
+  internal `<lyra-zoomable-frame>`. `false` (the default) preserves the exact pre-`zoomable` DOM — an
+  inline thumbnail (e.g. in a chat stream) must not unexpectedly grow a focusable zoom-chrome
+  viewport; an inspection surface opts in.
+- `highlights: LyraHighlight[] = []` (attribute: false) — display-only `region` highlights painted
+  over the image-format preview; ignored for the `text`/`generic` formats.
+- `activeHighlightId: string | null = null` (attribute `active-highlight-id`) — the `highlights`
+  entry, if any, currently treated as active (`data-active` on its `region-highlight`).
+- `anchorKinds` is a readonly `['region']` (this viewer's supported `LyraAnchor.kind` values for the
+  shared anchor-target contract).
+
+**Methods:** `scrollToAnchor(target)` — scrolls a `region` highlight (by id, or a `LyraAnchor`
+matched back to its owning `LyraHighlight` by reference) into view; resolves `false` when nothing
+matches, the anchor isn't `region`, or the format isn't currently `image`.
 
 **Events:**
 - `lyra-download` — `detail: { src, filename }` — fired when the generic-download fallback's link is
@@ -7782,6 +9075,8 @@ image path — and the generic fallback simply omits `[part="download-link"]` en
 - `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.
+- `lyra-highlight-activate` — `detail: { id }` — a region highlight was clicked or activated via
+  Enter/Space (image format only).
 
 **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
@@ -7792,7 +9087,11 @@ download fallback for any `mime-type` this component doesn't natively support. I
 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 *and* passes the link-safe scheme allowlist — see the URL-safety note
-above; excludes `data:` even though the other two sinks allow it)
+above; excludes `data:` even though the other two sinks allow it), `highlight-layer` (wrapper around
+every rendered region highlight, image format only), `region-highlight` (one region highlight,
+`data-tone`, `data-active`; image format only), `frame-viewport`/`frame-content`/`frame-controls`/
+`frame-zoom-in`/`frame-zoom-out`/`frame-reset` (forwarded from the internal `<lyra-zoomable-frame>`
+while `zoomable`; image format only)
 
 **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
@@ -7877,6 +9176,13 @@ type. First-party invention.
 - `src: string = ''` — source URL passed to the selected renderer or the fallback preview.
 - `registry?: DocumentRendererRegistry` (attribute: false) — optional per-instance registry override;
   the module-level registry is used when unset.
+- `alt: string = ''` — media alt text forwarded to the resolved renderer, for image-like renderers.
+- `anchor: LyraAnchor | string | null = null` (attribute: false) — declarative scroll-to-anchor
+  target forwarded to the resolved renderer; a string is a highlight id in `highlights`.
+  `hasChanged: () => true`, so re-assigning the same value (e.g. re-clicking the same citation
+  badge) still re-fires.
+- `highlights: LyraHighlight[] = []` (attribute: false) — highlights forwarded to the resolved
+  renderer.
 
 **Events:**
 - `lyra-close` — `detail: DocumentViewerCloseReason`, the nested dialog's dismissal reason. The
@@ -7928,13 +9234,33 @@ Mammoth preserves document structure such as headings, paragraphs, lists, tables
 not intended to reproduce pixel-exact Word page layout. There is no unsanitized rendering escape
 hatch: if `dompurify` is unavailable, rendering is blocked even when Mammoth converted successfully.
 
+Every rendered heading's slug (the same GitHub-slugger-style algorithm `<lyra-markdown>` uses) is
+stamped as its `id` and cached into `getHeadingTree()`'s document-ordered outline. Adopts
+`DocumentAnchorTarget`: `fragment` anchors resolve against that outline, `text-quote` anchors via
+the shared quote-scoping helpers; `highlights` re-resolve by quote after every render.
+
 **Properties:** `src`, `name`, and `maxHeight` (attribute `max-height`) are strings. `maxHeight` caps
-the scrollable document body.
+the scrollable document body. `anchorKinds` is a readonly `['fragment', 'text-quote']` (this
+viewer's supported `LyraAnchor.kind` values for the shared anchor-target contract).
+
+**Methods:** `getHeadingTree()` returns the document-ordered outline as `DocxHeadingItem[]` (`{ id,
+label, level }`), cached on every successful load. `search(query)` resolves the match count via a
+case-insensitive substring search over the rendered content's text (empty/whitespace query behaves
+like `clearSearch()`); `searchNext()`/`searchPrevious()` advance/step back through matches
+(wrapping, resolving `false` when there are none); `clearSearch()` clears the query, matches, and
+painted marks.
 
 **Events:** `lyra-render-error` with `detail.error` when fetching, conversion, sanitization, or a
-non-fatal Mammoth conversion message occurs.
+non-fatal Mammoth conversion message occurs. `lyra-search-change` (`detail: { query, matchCount,
+activeIndex }`) — from `search()`/`searchNext()`/`searchPrevious()`/`clearSearch()`.
+`lyra-highlight-activate` (`detail: { id }`) — a painted `text-quote` highlight was clicked.
+`lyra-text-select` (`detail: { text, anchor, rects }`) — fired on selection end inside the rendered
+content. `lyra-anchor-result` (`detail: { found }`) — fired after an `anchor` assignment or a
+`scrollToAnchor()` call.
 
-**CSS parts:** `base`, `body`, `content`, `spinner`, and `error`.
+**CSS parts:** `base`, `body`, `content`, `spinner`, `error`, `highlight` (a painted `text-quote`
+highlight), `search-match` (a painted in-document search match), and `search-match-active` (the
+currently active search match, also carries `search-match`).
 
 **Optional peer dependencies:** install `mammoth` and `dompurify` with `pnpm add mammoth dompurify`.
 The component registers an eager `application/vnd.openxmlformats-officedocument.wordprocessingml.document`
@@ -7959,13 +9285,17 @@ remain available without DOMPurify. Attachments are listed as filename and size
 Remote resources are capped at 25 MB; exceeding it surfaces the localized
 `documentPreviewResourceTooLarge` message instead of the message.
 
-**Properties:** `src`, `name`, and `maxHeight` (attribute `max-height`) are strings.
+**Properties:** `src`, `name`, and `maxHeight` (attribute `max-height`) are strings. `foldQuotes:
+boolean = false` (attribute `fold-quotes`) — collapses trailing quoted-reply text/HTML behind a
+localized show/hide toggle. `false` (the default) preserves the full body rendering.
 
 **Events:** `lyra-render-error` with `detail.error` when fetching or parsing fails.
 
 **CSS parts:** `base`, `headers`, `from-label`, `from`, `to-label`, `to`, `subject-label`, `subject`,
 `date-label`, `date`, `body`, `body-html`, `body-text`, `attachments`, `attachments-label`,
-`attachment-list`, `attachment-item`, `spinner`, and `error`.
+`attachment-list`, `attachment-item`, `quoted` (a folded quoted-text block, hidden until expanded, only
+while `foldQuotes`), `quote-toggle` (the show/hide-quoted-text toggle button, only while `foldQuotes`),
+`spinner`, and `error`.
 
 **Optional peer dependencies:** install `postal-mime` and `dompurify` with
 `pnpm add postal-mime dompurify`. The component registers `message/rfc822` and falls back to
@@ -8021,19 +9351,48 @@ epub.js renders the reading area into its stable `mount` element, using an inter
 chapter content.
 
 **Properties:** `src` and `name` are strings. `accessibleLabel` (attribute `aria-label`) overrides
-the reading region's accessible name.
-
-**Events:** `lyra-render-error` with `detail.error` when fetching, opening, or rendering fails.
+the reading region's accessible name. `location: string = ''` (not reflected — CFIs are long) is
+a CFI or spine href identifying the current reading position: set before the book finishes
+loading it's recorded and applied once ready, set after it applies immediately, and epub.js's own
+`relocated` event keeps it in sync with user navigation without re-triggering its own `display()`
+call. `anchorKinds` is a readonly `['cfi', 'text-quote']` (this viewer's supported `LyraAnchor.kind`
+values for the shared anchor-target contract).
+
+**Methods:** `getToc()` resolves the EPUB's own navigation document (`book.navigation.toc`,
+populated once `book.ready` resolves) flattened into document-ordered `EbookTocItem[]` (`{ id,
+label, href, level }`, `level` starting at 1 for a top-level entry, `id` falling back to `href`
+when a navigation entry has none), `[]` before a book has loaded. `search(query)` resolves the
+match count across every spine section, in document order, via epub.js's own `item.load()`/
+`item.find()`/`item.unload()` (empty/whitespace query behaves like `clearSearch()`; a newer
+`search()` call or a `src` change aborts an in-flight scan); `searchNext()`/`searchPrevious()`
+advance/step back through matches (wrapping, resolving `false` when there are none); `clearSearch()`
+clears the query, matches, and painted search annotation.
+
+**Events:** `lyra-render-error` with `detail.error` when fetching, opening, or rendering fails;
+`lyra-location-change` (`detail: { cfi, href }`) fired from epub.js's own `relocated` event;
+`lyra-search-change` (`detail: { query, matchCount, activeIndex }`) from `search()`/`searchNext()`/
+`searchPrevious()`/`clearSearch()`.
 
 **CSS parts:** `base`, `toolbar`, `previous-button`, `next-button`, `previous-icon`, `next-icon`,
-`mount`, and `error`.
+`mount`, `error`, and `announcer` (the visually-hidden `role="status"` region search results
+announce through).
 
 **Optional peer dependency:** install `epubjs` with `pnpm add epubjs`. The document-viewer registry
-matches `application/epub+zip` and `.epub` filenames.
+matches `application/epub+zip` and `.epub` filenames, declaring `{ anchors: ['cfi', 'text-quote'],
+search: true, textSelect: true }` capabilities.
 
 Remote resources are capped at 25 MB; exceeding it surfaces the localized
 `documentPreviewResourceTooLarge` message instead of the ebook.
 
+Adopts the shared anchor-target contract (`highlights`, `activeHighlightId`, `scrollToAnchor()`,
+events `lyra-highlight-activate`/`lyra-text-select`/`lyra-anchor-result`): a `cfi` anchor displays
+directly via `rendition.display()`; a `text-quote` anchor resolves by scanning the spine with
+epub.js's own `item.find()`, since chapter content lives inside epub.js-owned iframes rather than
+this component's own shadow DOM — `lyra-text-select` mirrors epub.js's own `selected` event for the
+same reason. `highlights` (kind `cfi`) paint via `rendition.annotations.highlight()` and are
+re-applied whenever the rendition is recreated (a `src` change, or a reconnect remount), since
+epub.js doesn't persist annotations across a fresh `renderTo()`.
+
 ## `lyra-pptx-viewer`
 
 Best-effort client-side PPTX viewer backed by the optional `@aiden0z/pptx-renderer` peer. A
@@ -8066,10 +9425,10 @@ spreadsheet, presentation, code, archive, image, audio, and video formats. An ex
 type wins; filename extension fallback is used only for an empty or `application/octet-stream`
 MIME type. Unknown values return a generic file result.
 
-**Properties:** `mimeType` (attribute `mime-type`), `name`, `label`, `decorative`, and
-`variant: 'icon' | 'label'`.
+**Properties:** `mimeType` (attribute `mime-type`), `name`, `size` (bytes; `0` renders no size),
+`label`, `decorative`, and `variant: 'icon' | 'label'`.
 
-**CSS parts:** `base`, `icon`, and `label`.
+**CSS parts:** `base`, `icon`, `label`, and `size`.
 
 **Exports:** `LyraFileTypeMetadata`, `LyraFileTypeIcon`, `LyraFileTypeCategory`,
 `getFileTypeMetadata()`, and `registerFileTypeMetadata()` for application-specific mappings.
@@ -8083,11 +9442,28 @@ MIME type. Unknown values return a generic file result.
 Fetches an SVG document, sanitizes it with the optional `dompurify` peer, and renders it inline.
 
 **Properties:** `src`, `name`, and `maxHeight` (attribute `max-height`) are strings. `maxHeight` caps
-the scrollable body.
+the scrollable body. `zoomable: boolean = false` (reflected) — wraps the rendered content in an
+internal `<lyra-zoomable-frame>`. `false` (the default) preserves the exact pre-`zoomable` DOM — an
+inline thumbnail (e.g. in a chat stream) must not unexpectedly grow a focusable zoom-chrome viewport;
+an inspection surface opts in. `highlights: LyraHighlight[] = []` (attribute: false) — display-only
+`region` highlights painted over the rendered SVG. `activeHighlightId: string | null = null`
+(attribute `active-highlight-id`) — the `highlights` entry, if any, currently treated as active
+(`data-active` on its `region-highlight`). `anchorKinds` is a readonly `['region']` (this viewer's
+supported `LyraAnchor.kind` values for the shared anchor-target contract).
+
+**Methods:** `scrollToAnchor(target)` — scrolls a `region` highlight (by id, or a `LyraAnchor` matched
+back to its owning `LyraHighlight` by reference) into view; resolves `false` when nothing matches, the
+anchor isn't `region`, or the document isn't loaded yet (no retry loop — a caller invoking this before
+`src` resolves simply gets `false`).
 
 **Events:** `lyra-render-error` with `detail.error` when fetching or sanitizing fails.
+`lyra-highlight-activate` (`detail: { id }`) — a region highlight was clicked or activated via
+Enter/Space.
 
-**CSS parts:** `base`, `body`, `svg`, `spinner`, and `error`.
+**CSS parts:** `base`, `body`, `svg`, `spinner`, `error`, `highlight-layer` (wrapper around every
+rendered region highlight), `region-highlight` (one region highlight, `data-tone`, `data-active`),
+`frame-viewport`/`frame-content`/`frame-controls`/`frame-zoom-in`/`frame-zoom-out`/`frame-reset`
+(forwarded from the internal `<lyra-zoomable-frame>` while `zoomable`).
 
 **Optional peer dependency:** `dompurify`.
 
@@ -8112,23 +9488,44 @@ Remote resources are capped at 25 MB; exceeding it surfaces the localized
 
 ## `lyra-dataset-viewer`
 
-Fetches tab-, pipe-, or delimiter-separated text and renders an accessible table using the optional
-`papaparse` peer. The document registry matches `.tsv`, `.psv`, and `.dat` filenames.
+Fetches tab-, pipe-, or delimiter-separated text and renders a virtualized, accessible table (a
+`role="table"` container with a sticky `role="row"` header, composed with `<lyra-virtual-list
+item-role="row">` for the body) using the optional `papaparse` peer. The document registry matches
+`.tsv`, `.psv`, and `.dat` filenames.
 
-**Properties:** `src`, `name`, and `maxHeight` (attribute `max-height`) are strings.
+Adopts `DocumentAnchorTarget`: a `cell-range` anchor addresses the raw file grid, 1-based, with the
+header row always occupying row 1 (this component always parses with a header row, so the first row
+is never part of the virtualized body); `scrollToAnchor()` scrolls the addressed row into view via
+the virtualized list's `active-id`. `highlights` paint as a `part="cell-highlight"` cell wrapping a
+focusable `part="cell-highlight-action"` native button, keeping the ARIA table tree intact.
+
+**Properties:** `src`, `name`, and `maxHeight` (attribute `max-height`) are strings. `anchorKinds` is
+a readonly `['cell-range']` (this viewer's supported `LyraAnchor.kind` values for the shared
+anchor-target contract).
+
+**Methods:** `search(query)` resolves the match count via a case-insensitive substring search over
+every body cell's raw string value, ordered row then column (empty/whitespace query behaves like
+`clearSearch()`); `searchNext()`/`searchPrevious()` advance/step back through matches (wrapping,
+resolving `false` when there are none); `clearSearch()` clears the query, matches, and cursor.
 
 **Events:** `lyra-render-error` with `detail.error` when fetching or parsing fails.
+`lyra-highlight-activate` (`detail: { id }`) — a `highlights` cell was clicked or activated via
+Enter/Space. `lyra-anchor-result` (`detail: { found }`) — fired after an `anchor` assignment or a
+`scrollToAnchor()` call. `lyra-search-change` (`detail: { query, matchCount, activeIndex }`) — from
+`search()`/`searchNext()`/`searchPrevious()`/`clearSearch()`.
 
-**CSS parts:** `base`, `body`, `table`, `spinner`, and `error`.
+**CSS parts:** `base`, `body`, `table`, `header-row`, `header-cell`, `data-row`, `cell`,
+`cell-highlight` (a `role="cell"` covered by a `highlights` entry; wraps the action button),
+`cell-highlight-action` (the native button filling a highlighted cell — focusable, emits
+`lyra-highlight-activate` on click or Enter/Space), `spinner`, and `error`.
 
 **Exports:** `DatasetTable` is `{ fields: string[]; rows: Record<string, string>[] }`.
 
 **Optional peer dependency:** `papaparse`.
 
-Remote resources are capped at 25 MB, and the parsed table at 1,000 rows and 1,000 columns (lower
-than `lyra-csv-viewer`/`lyra-spreadsheet-viewer`'s shared 10,000-row cap, since this component renders
-every row into a real, non-virtualized `<table>` in one synchronous pass); exceeding any of these
-surfaces the localized `documentPreviewResourceTooLarge` message instead of the table.
+Remote resources are capped at 25 MB, and the parsed table at 10,000 rows and 1,000 columns (the
+same shared default as `lyra-csv-viewer`/`lyra-spreadsheet-viewer`); exceeding either surfaces the
+localized `documentPreviewResourceTooLarge` message instead of the table.
 
 ## `lyra-contact-viewer`
 
@@ -8156,13 +9553,23 @@ Fetches a PDF and renders its pages with the optional `pdfjs-dist` peer. Pages a
 `lyra-virtual-list`, and PDF.js's selectable text layer is positioned over each rendered canvas.
 
 **Properties:** `src` and `name` are strings. `page: number = 1` is the one-based current page and
-`zoom: number = 1` is clamped to `0.25`–`4`.
+`zoom: number = 1` is clamped to `0.25`–`4`. `anchorKinds` is a readonly `['page', 'text-quote',
+'region']` (this viewer's supported `LyraAnchor.kind` values for the shared anchor-target contract).
 
 **Events:** `lyra-render-error` with `detail.error` when fetching, parsing, or rendering fails;
 `lyra-page-change` with `{ page, pageCount }`; and `lyra-zoom-change` with `{ zoom }`.
 
 **Methods:** `nextPage()`, `previousPage()`, `zoomIn()`, and `zoomOut()` update the corresponding
-controlled state within its supported range.
+controlled state within its supported range. `getPageText(page)` resolves the raw reading-order text
+of one page (per-page LRU-cached, 64 pages), rejecting on no loaded document or an out-of-range page.
+`renderPageThumbnail(page, canvas, options?)` renders `page` into a caller-owned `canvas` at
+`options.width` CSS px (default 96), devicePixelRatio-aware, resolving `false` when not ready or out
+of range. `goToPage(page)` scrolls the virtualized list to `page`, resolving `true` once mounted (or
+`false` for an out-of-range value, without changing `page`). `getOutline()` resolves the document's
+table of contents as `PdfOutlineItem[]` (`{ title, page?, children? }`), `[]` when there is none.
+`search(query)` resolves the match count across all pages (empty/whitespace query behaves like
+`clearSearch()`); `searchNext()` and `searchPrevious()` advance/step back through matches (wrapping,
+resolving `false` when there are none); `clearSearch()` clears the query, matches, and painted marks.
 
 **CSS parts:** `base`, `toolbar`, `page-indicator`, `zoom-indicator`, `pages`, `page`, `text-layer`,
 `spinner`, and `error`.
@@ -8179,14 +9586,31 @@ Remote resources are capped at 25 MB; exceeding it surfaces the localized
 Fetches and renders `.xlsx` and `.xls` workbooks with the optional `xlsx` (SheetJS) peer. Multiple
 worksheets render through a `<lyra-tabs>` switcher, and body rows use `<lyra-virtual-list>`.
 
-**Properties:** `src` and `name` are strings.
+Adopts `DocumentAnchorTarget`: a `cell-range` anchor addresses one sheet's raw grid, 1-based, with
+its header row included, resolving the target sheet from the anchor's own `sheet` field (falling
+back to a `Sheet!`-prefixed `range`, then the active sheet); `scrollToAnchor()` switches
+`<lyra-tabs>`'s active tab first when needed, then scrolls the addressed row/column into view.
+`highlights` paint as a focusable `part="cell-highlight"`.
+
+**Properties:** `src` and `name` are strings. `anchorKinds` is a readonly `['cell-range']` (this
+viewer's supported `LyraAnchor.kind` values for the shared anchor-target contract).
+
+**Methods:** `search(query)` resolves the match count across every sheet's stringified cell values,
+ordered sheet then row then column, switching tabs as navigation crosses sheets (empty/whitespace
+query behaves like `clearSearch()`); `searchNext()`/`searchPrevious()` advance/step back through
+matches (wrapping, resolving `false` when there are none); `clearSearch()` clears the query,
+matches, and painted marks.
 
 **Events:** `lyra-render-error` with `detail.error` when fetching or parsing fails.
+`lyra-highlight-activate` (`detail: { id }`) — a `highlights` cell was clicked or activated via
+Enter/Space. `lyra-anchor-result` (`detail: { found }`) — fired after an `anchor` assignment or a
+`scrollToAnchor()` call. `lyra-search-change` (`detail: { query, matchCount, activeIndex }`) — from
+`search()`/`searchNext()`/`searchPrevious()`/`clearSearch()`.
 
-**CSS parts:** `base`, `tabs`, `sheet`, `header-row`, `data-row`, `cell`, `rows`, `spinner`, and
-`error`.
+**CSS parts:** `base`, `tabs`, `sheet`, `header-row`, `data-row`, `cell`, `cell-highlight` (a cell
+covered by a `highlights` entry), `rows`, `spinner`, and `error`.
 
-**Optional peer dependency:** install `xlsx` with `pnpm add xlsx`. The registry matches the official
+**Optional peer dependency:** install `xlsx` with `pnpm add https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz`. The official CDN matches the
 `.xlsx` and `.xls` MIME types and filename extensions.
 
 Remote resources are capped at 25 MB, and each parsed sheet at 10,000 rows and 1,000 columns;
@@ -8197,12 +9621,30 @@ the workbook.
 
 Fetches CSV text, parses quoted fields with the optional `papaparse` peer, and virtualizes body rows.
 
+Adopts `DocumentAnchorTarget`: a `cell-range` anchor addresses the raw file grid, 1-based, with the
+header row included whenever `has-header-row` is set; `scrollToAnchor()` scrolls the addressed
+row/column into view via the virtualized list's `active-id`. `highlights` paint as a focusable
+`part="cell-highlight"`.
+
 **Properties:** `src` and `name` are strings. `hasHeaderRow: boolean = true` (attribute
 `has-header-row`) controls whether the first parsed row is rendered as a sticky header.
+`anchorKinds` is a readonly `['cell-range']` (this viewer's supported `LyraAnchor.kind` values for
+the shared anchor-target contract).
+
+**Methods:** `search(query)` resolves the match count via a case-insensitive substring match over
+the same stringified cell values `cell()` renders, ordered row then column (empty/whitespace query
+behaves like `clearSearch()`); `searchNext()`/`searchPrevious()` advance/step back through matches
+(wrapping, resolving `false` when there are none); `clearSearch()` clears the query, matches, and
+painted marks.
 
 **Events:** `lyra-render-error` with `detail.error` when fetching or parsing reports an error.
+`lyra-highlight-activate` (`detail: { id }`) — a `highlights` cell was clicked or activated via
+Enter/Space. `lyra-anchor-result` (`detail: { found }`) — fired after an `anchor` assignment or a
+`scrollToAnchor()` call. `lyra-search-change` (`detail: { query, matchCount, activeIndex }`) — from
+`search()`/`searchNext()`/`searchPrevious()`/`clearSearch()`.
 
-**CSS parts:** `base`, `sheet`, `header-row`, `data-row`, `cell`, `rows`, `spinner`, and `error`.
+**CSS parts:** `base`, `sheet`, `header-row`, `data-row`, `cell`, `cell-highlight` (a cell covered by
+a `highlights` entry), `rows`, `spinner`, and `error`.
 
 **Optional peer dependency:** install `papaparse` with `pnpm add papaparse`. The registry matches
 `text/csv` and `.csv` filenames.
@@ -8880,6 +10322,41 @@ Groups avatars and collapses excess members into a localized overflow indicator.
 `max`, `shape`, `size`, and `tone`. The default slot accepts avatar elements. **CSS parts:** `base`,
 `avatars`, and `overflow`.
 
+## `lyra-emoji-picker`
+
+A searchable, keyboard-navigable, form-associated emoji picker. `groups` is fully consumer-suppliable
+— the component ships no emoji data of its own — in the same "zero/optional-peer dependency" spirit
+as `<lyra-lite-chart>`/`<lyra-heatmap>`; an optional convenience auto-loader fetches a default set on
+connect from the `emoji-picker-element-data` peer, but only when `groups` hasn't already been
+supplied (an explicit empty array still counts as supplied and skips the auto-load).
+
+**Properties:** the shared form properties `name`, `value`, `disabled`, and `required`, plus
+`groups: EmojiPickerGroup[] = []` (attribute: false) — `EmojiPickerGroup { key, label, emojis:
+EmojiPickerItem[] }`, `EmojiPickerItem { emoji, name, shortcodes? }`; the search field matches `name`
+and every `shortcodes` entry, case-insensitively. Empty (the default, before the auto-loader
+resolves) renders just the search input and the empty state. `accessibleLabel` (`aria-label`)
+forwards a host-supplied accessible name to the internal `role="listbox"` grid; empty falls back to
+the localized default grid label.
+
+**Events:** `lyra-change` with `detail: { emoji }` (an emoji was picked — click, or Enter/Space on
+the active grid cell; also sets `value`), plus the shared form `input`, `change`, `focus`, and `blur`.
+
+**Keyboard:** the grid is a roving-tabindex listbox (a single Tab stop — only the active emoji is
+tabbable). ArrowLeft/ArrowRight step the active item backward/forward following reading direction
+(swapped under RTL), ArrowUp/ArrowDown move by one visual row (measured from the live wrap layout),
+Home/End jump to the first/last item, and Enter/Space picks the active item. The search input is a
+`role="combobox"` over the same listbox: the arrow keys and Enter also work while focus stays in
+the input, with `aria-activedescendant` tracking the active option. Hovering an emoji with the
+pointer also moves the active item to it.
+
+**CSS parts:** `base`, `search` (`role="combobox"`), `grid` (`role="listbox"`), `group-label`,
+`emoji` (each emoji's own `role="option"` button), `empty` (shown when the search matches nothing).
+
+**Optional peer dependency:** install `emoji-picker-element-data` with
+`pnpm add emoji-picker-element-data` for the built-in auto-loaded default emoji set — omit it and
+supply `groups` directly instead. The loader never throws; a missing or failed peer logs one
+`console.warn` and simply leaves `groups` empty.
+
 ## `lyra-include`
 
 Loads HTML or text from `src` into the component. **Properties:** `src` and `mode` (`html` or `text`).
@@ -8988,3 +10465,1130 @@ These apply across the whole library rather than to any one component:
 - **RTL.** Components generally rely on CSS logical properties to flip layout for free; `lyra-split`
   and `lyra-time-range` additionally consult `internal/rtl.ts`'s `isRtl()` to mirror the physical
   drag-direction/arrow-key math that logical properties alone don't cover.
+
+## `lyra-audio-visualizer`
+
+A presentational, canvas-drawn voice-activity visualization (bars or waveform) — the
+LiveKit-BarVisualizer counterpart for this library. Driven by a `MediaStream` (lazily wired to a
+WebAudio `AnalyserNode`), a numeric `level` for hosts that already compute levels (e.g.
+`<lyra-push-to-talk>`'s `lyra-level`), or `state` alone for an ambient animation when no real signal
+exists. A real signal (`stream` or `level`) always drives amplitude regardless of
+`prefers-reduced-motion`; only the signal-less ambient animation is throttled under reduced motion.
+
+**Properties:** `stream: MediaStream | null = null` (attribute: false), `level: number | null = null`,
+`state: 'idle' | 'listening' | 'thinking' | 'speaking' = 'idle'` (reflected), `variant: 'bars' |
+'waveform' = 'bars'` (reflected), `barCount: number = 5` (attribute `bar-count`), `gain: number = 1`,
+and `label: string = ''`.
+
+**Methods:** `refreshTheme()` re-reads themeable custom properties after a runtime theme change.
+
+**CSS parts:** `base` (the root wrapper) and `canvas` (the drawing surface, `aria-hidden`; the host
+itself carries `role="img"` and the accessible name).
+
+**Themeable custom properties:** `--lyra-audio-visualizer-color` (default `--lyra-color-brand` —
+active bar/waveform color) and `--lyra-audio-visualizer-quiet-color` (default
+`--lyra-color-brand-quiet` — inactive/idle color).
+
+## `lyra-branch-picker`
+
+The "‹ 2 / 5 ›" navigator across regenerated/edited variants of one message. Pure controlled: it
+never mutates its own `index` — the same contract `<lyra-pagination>` already establishes for
+`page`. The host listens for `lyra-branch-change`, swaps the displayed branch content, and applies
+the new `index` back. Renders nothing at all while `count < 2`, so a host can bind it unconditionally
+on every message regardless of whether that message actually has multiple branches yet.
+
+**Properties:** `index: number = 0` (reflected) and `count: number = 1` (reflected) — the current
+0-based branch and the total branch count. `label: string = ''`.
+
+**Methods:** `focus()` and `blur()` forward to the group wrapper.
+
+**Events:** `lyra-branch-change` — a branch navigation was requested. `detail: { index }`, always a
+valid target (never past either bound); the consumer applies `index` after switching the displayed
+branch content.
+
+**CSS parts:** `base` (the group wrapper, `role="group"`), `previous-button`, `next-button`, and
+`position` (the visible "2 / 5" text).
+
+## `lyra-compare-panel`
+
+Side-by-side A/B output comparison with a winner vote (LMSYS-arena / LangSmith-pairwise style): two
+slotted panes, a vote bar, synchronized reading.
+
+**Properties:** `labelA: string = ''` (attribute `label-a`) and `labelB: string = ''` (attribute
+`label-b`) — pane headings. `vote: 'a' | 'b' | 'tie' | 'both-bad' | null = null` (reflected) — the
+recorded winner, host-writable to reflect a previously-recorded vote back. `itemId: string = ''`
+(attribute `item-id`) — an opaque id round-tripped through `lyra-vote`. `hideTie: boolean = false`
+(attribute `hide-tie`) and `hideBothBad: boolean = false` (attribute `hide-both-bad`) hide the
+corresponding vote button. `syncScroll: boolean = false` (attribute `sync-scroll`) links both panes'
+scroll position.
+
+**Slots:** `a` (the first output — any content, a chat message, markdown, a viewer), `b` (the second
+output), and `prompt` (optional shared-input header above both panes).
+
+**Events:** `lyra-vote` — `detail: { choice, itemId }`.
+
+**CSS parts:** `base` (the outer wrapper), `prompt` (the optional prompt header, hidden when the
+`prompt` slot is empty), `panes` (the row, or under 640px column, wrapping both panes), `pane-a`,
+`pane-b` (each pane's labeled scroll region), `pane-header` (a pane's visible heading), `vote-bar`
+(the `role="group"` row of vote buttons), `vote-button` (one vote button), and `live-region` (the
+internal vote-announcement live region).
+
+## `lyra-highlight-layer`
+
+A presentational overlay that paints highlight rectangles (percent-of-box coordinates) over
+positioned content and owns their activation, active/flash styling, and keyboard access. `items`
+order is the caller's own reading order; the layer does not re-sort geometrically. Fills its nearest
+positioned ancestor.
+
+**Properties:** `items: HighlightLayerItem[] = []` (attribute: false), `activeId: string | null =
+null` (attribute `active-id`), and `interactive: boolean = true` (reflected) — gates click/keyboard
+activation.
+
+**Methods:** `flash(id)` briefly re-triggers the flash styling for an already-rendered rect (e.g. a
+re-click of the same source citation).
+
+**Events:** `lyra-highlight-activate` — a rect was activated (click, or Enter/Space while focused).
+`detail: { id }`.
+
+**CSS parts:** `base` (the absolutely-positioned overlay, inset 0) and `rect` (one highlight
+rectangle; carries `data-tone`/`data-active`/`data-flash` state attributes).
+
+## `lyra-message-actions`
+
+The per-message action toolbar for `lyra-chat-message`'s `actions` slot: opt-in built-ins (copy /
+regenerate / edit / feedback) that emit intent events, plus a default slot for custom controls (e.g.
+a slotted `lyra-branch-picker`). `role="toolbar"` with WAI-ARIA APG roving-tabindex; ArrowLeft/
+ArrowRight (RTL-aware) plus Home/End move focus across every stop — built-ins and slotted controls
+alike — via `.focus()`. Only the plain-button built-ins (`regenerate`/`edit`) get their `tabindex`
+toggled by this component itself; a composite child (`lyra-copy-button`, the `feedback` built-in, any
+slotted custom element) remains independently reachable via the page's native Tab order alongside the
+toolbar's single roving stop, since a shadow-root-internal focusable element can't be suppressed from
+outside its own component.
+
+**Properties:** `controls: MessageActionControl[] = []` (attribute: false, each `'copy' |
+'regenerate' | 'edit' | 'feedback'`) — which built-ins render, in that order. `copyText: string = ''`
+(attribute `copy-text`) — required for the `copy` built-in to render at all. `feedbackValue: 'up' |
+'down' | null = null` (attribute `feedback-value`) — forwarded to the embedded, thumbs-only
+`lyra-message-feedback` (its `reasons`/`commentable`/`detailFor` are never forwarded, so its detail
+panel never opens). `revealOnHover: boolean = false` (reflected, attribute `reveal-on-hover`) — hides
+the bar until the closest `lyra-chat-message` ancestor is hovered or a control inside has focus.
+`label: string = ''` — accessible name override for the toolbar. `accessibleLabel: string | null =
+null` (attribute `aria-label`) — overrides the toolbar's computed accessible name, winning over
+`label` and the localized default; attribute-reflects from a host-level `aria-label`.
+
+**Events:** `lyra-regenerate`/`lyra-edit` — a built-in was activated, no detail. `lyra-copy` —
+`detail: { text }`, surfaced by the embedded `lyra-copy-button` (bubbles/composed already, not
+re-emitted). `lyra-change`/`lyra-submit` — bubble unchanged from the embedded, thumbs-only
+`lyra-message-feedback`.
+
+**Slots:** default — additional controls (e.g. `lyra-copy-button`, `lyra-icon-button`,
+`lyra-branch-picker`) appended after the built-ins; they participate in the toolbar's arrow-key
+navigation.
+
+**CSS parts:** `base` (the toolbar, `role="toolbar"`), `copy-button` (the embedded
+`lyra-copy-button`), `regenerate-button`, `edit-button`, and `feedback` (the embedded
+`lyra-message-feedback`).
+
+## `lyra-message-feedback`
+
+Thumbs up/down for one assistant message, with an optional inline detail step (categorical reason
+chips + a free-text comment) that opens as a disclosure directly below the thumbs. Emits; never
+persists — a host reflects a previously-recorded rating back via `value` (+ `disabled` for a
+read-only display). Activating the pressed thumb again toggles it off to `null` unless its own detail
+panel is currently open, in which case that click re-opens the panel instead.
+
+**Properties:** `value: 'up' | 'down' | null = null` (reflected), `reasons: MessageFeedbackReason[] =
+[]` (attribute: false, each `{ id, label }`), `commentable: boolean = false` (reflected) adds a
+free-text comment field, `detailFor: 'down' | 'both' = 'down'` (attribute `detail-for`) — which
+rating opens the detail panel, and `disabled: boolean = false` (reflected) for a read-only display.
+
+**Methods:** `focus()` focuses the thumb matching the current `value` (the up thumb when `null`);
+`blur()` blurs both thumbs.
+
+**Events:** `lyra-change` — `detail: { value }`, fired when a thumb's rating changes or clears.
+`lyra-submit` — `detail: { value, reasonIds, comment }`, fired by the panel's submit button.
+
+**CSS parts:** `base` (the root), `thumbs` (wrapper around both thumb buttons), `up-button`,
+`down-button`, `panel` (the inline detail disclosure, only rendered when `reasons` is non-empty or
+`commentable` is set), `reasons` (the reason-chip group), `comment` (the comment `<textarea>`), and
+`submit-button`.
+
+## `lyra-page-rail`
+
+A virtualized vertical thumbnail rail for page-addressed documents, with per-page highlight heat
+markers. Two modes: **wired** (`viewer`/`for` supply a live page source, e.g. `<lyra-pdf-viewer>` —
+thumbnails render lazily as rows materialize, and the rail tracks page/count from the viewer's own
+events) and **mediated** (`page-count`/`page` are host-bound directly, rows render a placeholder
+glyph — still a fully functional pager). In wired mode the viewer's `page` is the single source of
+truth.
+
+**Properties:** `viewer: PageThumbnailSource | null = null` (attribute: false) — the wired viewer.
+`for: string = ''` — an id selector alternative to setting `viewer` directly. `pageCount: number = 0`
+(attribute `page-count`) and `page: number = 1` (reflected) — mediated-mode page state.
+`highlights: LyraHighlight[] = []` (attribute: false) — drives the per-page heat markers.
+`thumbWidth: number = 96` (attribute `thumb-width`) and `label: string = ''`.
+
+**Events:** `lyra-page-select` — a page row was activated (click, or Enter/Space on a focused row).
+`detail: { page }`. In wired mode the rail also sets `viewer.page` itself.
+
+**CSS parts:** `base` (the rail), `pages` (the embedded `<lyra-virtual-list>`), `page` (one page
+button), `thumbnail` (the thumbnail canvas wrapper), `page-number` (the visible page number), `heat`
+(the heat-marker cluster), and `heat-dot` (one tone-colored heat marker, or the `+n` overflow
+marker).
+
+**Themeable custom properties:** `--lyra-page-rail-height` (default `var(--lyra-size-24rem)`) — block
+size of the virtualized rail.
+
+## `lyra-push-to-talk`
+
+A mic capture button owning the full `getUserMedia` + `MediaRecorder` lifecycle: permission request,
+recording, optional chunked streaming, teardown. The one place in this library that touches the
+microphone — no SDK, no LiveKit/ElevenLabs import, native browser APIs only. `mode="hold"` (the
+default) is a press-and-hold gesture; `mode="toggle"` is click-to-start/click-to-stop with
+`aria-pressed`. Escape cancels the in-progress take in either mode.
+
+**Properties:** `mode: 'hold' | 'toggle' = 'hold'` (reflected), `timesliceMs: number = 0` (attribute
+`timeslice-ms`), `mimeType: string = ''` (attribute `mime-type`), `deviceId: string = ''` (attribute
+`device-id`), `audioConstraints?: MediaTrackConstraints` (attribute: false), `levelEvents: boolean =
+false` (attribute `level-events`), `maxDurationMs: number = 0` (attribute `max-duration-ms`),
+`showTimer: boolean = true` (attribute `show-timer`), `disabled: boolean = false` (reflected), and
+readonly `state: 'idle' | 'requesting' | 'denied' | 'recording' | 'error' = 'idle'` (reflected to
+`data-state`), and readonly `stream: MediaStream | null`.
+
+**Methods:** `start()`, `stop()`, and `cancel()` drive the capture lifecycle imperatively (mirroring
+the pointer/keyboard gestures).
+
+**Slots:** `icon` (replaces the default mic glyph) and `recording-icon` (replaces the default
+recording-state pulse glyph).
+
+**Events:** `lyra-record-start` (`detail: { stream }`), `lyra-record-chunk` (`detail: { blob }`, only
+when `timeslice-ms > 0`), `lyra-record-stop` (`detail: { blob, durationMs }`), `lyra-record-cancel`
+(no detail), `lyra-record-error` (`detail: { error }`), `lyra-level` (`detail: { level }`, opt-in via
+`level-events`), and `lyra-state-change` (`detail: { state }`).
+
+**CSS parts:** `trigger` (the capture button), `icon`, `pulse` (rendered only while recording),
+`timer` (the `M:SS` elapsed-time readout, only while recording and `show-timer`), and `status`
+(visible status text for the `requesting`/`denied`/`error`/unsupported states).
+
+## `lyra-rubric-form`
+
+A configurable annotation rubric (LangSmith annotation-queue style): score, category, and
+freeform-comment keys with a submit-and-next flow for working through an eval queue. Each
+`RubricKey.type` routes to an existing sibling control: `score` renders `<lyra-segmented>` or
+`<lyra-slider>`; `category` renders `<lyra-select>` or `<lyra-checkbox-group>` (`multiple`); `comment`
+renders `<lyra-textarea>`.
+
+**Properties:** `keys: RubricKey[] = []` (attribute: false, each `{ key, type, label?, description?,
+required?, min?, max?, step? }`), `value: RubricValue = {}` (attribute: false), `itemId: string = ''`
+(attribute `item-id`, reflected), `hasNext: boolean = false` (attribute `has-next`), `skippable:
+boolean = false`, and the shared form properties `name` and `disabled`. `errors: Record<string,
+string>` is the current per-key validation-message state.
+
+**Slots:** `actions` — extra host controls rendered in the footer beside Submit/Skip.
+
+**Events:** `lyra-input` (`detail: { value }`), `lyra-validity-change` (`detail: { valid, errors }`,
+fired only on an actual change), `lyra-submit` (`detail: { value, itemId }`), and `lyra-skip`
+(`detail: { itemId }`, `skippable` only).
+
+**CSS parts:** `base` (the outer wrapper), `field` (one key's wrapper), `label`, `description`,
+`scale` (the rendered score/category/comment control's wrapper), `error` (a field-level validation
+message), `footer`, `submit`, `skip` (only rendered when `skippable`), `empty` (shown when `keys` has
+no entries), and `unsupported` (the fallback note for a key whose `type` is outside the three
+supported ones).
+
+## `lyra-span-waterfall`
+
+The horizontal-timeline projection of the same `LyraSpan[]` `<lyra-trace-tree>` consumes: a time
+axis, one row per span in start order, status-toned bars (Langfuse timeline / Temporal
+event-history style).
+
+**Properties:** `spans: LyraSpan[] = []` (attribute: false), `activeSpanId: string | null = null`
+(attribute `active-span-id`), `viewStartMs: number | null = null` (attribute `view-start-ms`) and
+`viewEndMs: number | null = null` (attribute `view-end-ms`) — override the auto-computed time
+window, `hideAxis: boolean = false` (attribute `hide-axis`), and `label: string = ''`.
+
+**Events:** `lyra-span-select` — `detail: { id }`, a bar/row was activated (click, Enter, Space).
+
+**CSS parts:** `base`, `axis` (the time-ruler row, hidden when `hideAxis`), `tick`, `tick-label`,
+`row`, `name` (the row's name gutter), `bar-track`, `bar` (the interactive, focusable status-toned
+bar), `meta` (secondary row info, shown inline under 480px), `status-text`, `duration`, `empty` (shown
+when `spans` is empty), and `live-region`.
+
+**Themeable custom properties:** `--lyra-span-waterfall-name-width` (default `8rem`) and
+`--lyra-span-waterfall-stripe-speed` (a `running` span's striped-bar animation duration; defaults to
+`--lyra-transition-ambient`).
+
+## `lyra-task-list`
+
+A live, collapsible tracker for an agent's plan: ordered steps with per-step lifecycle status and one
+level of nested sub-steps, embedded in the transcript. `items` is controlled and never mutated by this
+component. Unlike `<lyra-stepper>`'s single-`current` navigation, task-list is a read-only status
+report: several steps may be `running` at once, there is no selection, and status changes are
+announced through an internal `<lyra-live-region>`.
+
+**Properties:** `items: TaskItem[] = []` (attribute: false, each `{ id, label, status, detail?,
+children? }` where `status` is `'pending' | 'running' | 'success' | 'error'`), `label: string =
+'Tasks'`, `expanded: boolean = true` (reflected), and `collapsible: boolean = true`.
+
+**Slots:** `detail-<id>` — dynamic, one per item id (e.g. `slot="detail-step-3"`); rich detail under
+that item's label, typically a `<lyra-tool-call-chip>` or file `<lyra-chip>`.
+
+**Events:** `lyra-toggle` — the header was activated, expanding or collapsing the panel. `detail: {
+expanded }`.
+
+**CSS parts:** `base`, `header` (a `<button>` when `collapsible`, a plain heading otherwise), `label`,
+`summary` (the visible "N of M completed" summary, top-level items only), `toggle` (the chevron
+indicator, only rendered when `collapsible`), `body` (the list of items, `hidden` while collapsed),
+`item` (`role="listitem"`; carries `data-status`/`data-id`/`data-depth`), `status-icon`, `item-label`,
+`item-detail`, and `item-children` (the nested `role="list"` wrapper around a top-level item's
+children).
+
+**Themeable custom properties:** `--lyra-task-list-spin` (default `1s linear`) — running-status icon
+spin animation duration/timing.
+
+## `lyra-terminal`
+
+A read-only ANSI console for streamed agent/tool output. Not a PTY: no stdin/keystroke handling, no
+cursor-addressed full-screen apps.
+
+**Properties:** `content: string = ''` — initial/replaceable buffer content, parsed for ANSI/SGR
+codes. `maxScrollback: number = 5000` (attribute `max-scrollback`), `follow: boolean = true`
+(reflected) — stick-to-bottom, `wrap: boolean = true` (reflected), `copyable: boolean = true`
+(reflected) and `downloadable: boolean = false` (reflected) toggle the toolbar buttons, `filename:
+string = 'terminal.log'`, `announceOutput: boolean = false` (attribute `announce-output`),
+`accessibleLabel: string = ''` (attribute `aria-label`), `highlights: LyraHighlight[] = []` (attribute:
+false), and `activeHighlightId: string | null = null` (attribute: false). `anchorKinds` is a readonly
+`['page', 'text-quote', 'region']` for the shared anchor-target contract.
+
+**Methods:** `write(text)` appends ANSI-parsed text to the buffer. `clear()` empties the buffer.
+`scrollToBottom()` and `scrollToAnchor(anchor)` control scroll position. `search(query)`,
+`searchNext()`, `searchPrevious()`, and `clearSearch()` drive in-buffer text search. `getPlainText()`
+returns the SGR-stripped plain text of the whole buffer.
+
+**Events:** `lyra-copy` (`detail: { text }`), `lyra-download` (`detail: { filename }`),
+`lyra-follow-change` (`detail: { following }`), `lyra-search-change` (`detail: { query, matchCount,
+activeIndex }`), `lyra-highlight-activate` (`detail: { id }`), and `lyra-text-select` (`detail: {
+text, anchor, rects }`).
+
+**CSS parts:** `base`, `toolbar` (only rendered when copy/download are enabled), `copy-button`,
+`download-button`, `viewport` (the `role="log"` scrollable region), `line` (one rendered line; carries
+`data-line-number`/`data-match`/`data-highlight-tone`), `jump-to-latest` (shown while `follow` is
+disengaged and new output has arrived), and `announcer` (the visually-hidden `role="status"` region
+used when `announce-output` is set).
+
+## `lyra-trace-tree`
+
+A collapsible span hierarchy for one agent/LLM trace (Langfuse/LangSmith run-tree style): kind icon,
+name, status, an inline duration bar on the shared trace time scale, and optional tokens/cost
+columns. Consumes the same `LyraSpan[]` as `<lyra-span-waterfall>`.
+
+**Properties:** `spans: LyraSpan[] = []` (attribute: false), `activeSpanId: string | null = null`
+(attribute `active-span-id`), `label: string = ''`, `showTokens: boolean = false` (attribute
+`show-tokens`), `showCost: boolean = false` (attribute `show-cost`), and `hideBars: boolean = false`
+(attribute `hide-bars`).
+
+**Methods:** `expandAll()` and `collapseAll()` set every row's expanded state at once.
+
+**Events:** `lyra-span-select` (`detail: { id }`, a row was activated) and `lyra-span-toggle`
+(`detail: { id, expanded }`, a row was expanded or collapsed).
+
+**CSS parts:** `base` (`role="tree"`), `header` (the column-header row, only when
+`showTokens`/`showCost`), `row` (`role="treeitem"`), `toggle`, `icon`, `name`, `detail`, `status-text`,
+`duration`, `tokens-in`, `tokens-out` (when `showTokens`), `cost` (when `showCost`), `bar-track`,
+`bar`, `empty` (shown when `spans` is empty), and `live-region`.
+
+## `lyra-file-tree`
+
+A file-explorer preset over `<lyra-tree>` + `<lyra-file-icon>`: path-keyed nodes with
+git-status/diff-count badges, lazy directory loading, and select/open events.
+
+**Properties:** `nodes: FileTreeNode[] = []` (attribute: false), `selectedPath: string | null = null`
+(attribute `selected-path`), and `label: string = ''`.
+
+**Methods:** `setChildren(path, children)` supplies a lazily-loaded directory's children.
+`revealPath(path)` expands every ancestor directory and scrolls the target row into view, resolving
+`true` once found. `expandAll()` and `collapseAll()` forward to the underlying `<lyra-tree>`.
+
+**Events:** `lyra-file-select` (`detail: { path, node }`, a row was activated), `lyra-file-open`
+(`detail: { path, node }`, Enter/click on an already-selected file row), and `lyra-load-children`
+(`detail: { path }`, a lazy unloaded directory expanded).
+
+**CSS parts:** `base` — the root wrapper.
+
+## `lyra-activity-feed`
+
+An append-only streaming log of granular agent actions ("Searching the web…", "Read
+src/index.ts"), collapsing to a localized "Completed N steps" summary once the run is over. Entries
+never change state once added — a step whose status mutates in place belongs to `<lyra-task-list>`
+instead. Implements the shared follow (stick-to-bottom) contract. At/above `virtualizeThreshold`
+entries, the body renders through an internal `<lyra-virtual-list>` instead of a plain keyed list.
+
+**Properties:** `entries: ActivityEntry[] = []` (attribute: false), `mode: 'live' | 'post-hoc' =
+'live'` (reflected), `follow: boolean = true` (reflected), `expanded: boolean = false` (reflected),
+`label: string = 'Activity'`, `showTimestamps: boolean = false` (attribute `show-timestamps`),
+`formatTimestamp?: (date: Date) => string` (attribute: false), and `virtualizeThreshold: number =
+200` (attribute `virtualize-threshold`).
+
+**Events:** `lyra-toggle` (`detail: { expanded }`, the header was activated) and
+`lyra-follow-change` (`detail: { following }`, `follow` released or re-engaged).
+
+**CSS parts:** `base`, `header` (a `<button>`), `status-dot` (pulses while `mode="live"`),
+`summary`, `toggle`, `body` (the scrollable region, or the internal virtual-list), `entry` (carries
+`data-tone`), `entry-icon`, `entry-text`, and `entry-timestamp` (only while `showTimestamps` and a
+valid `timestamp` is set).
+
+**Themeable custom properties:** `--lyra-activity-feed-max-height` (default `16rem`) — cap on how
+tall the expanded body grows before it scrolls internally.
+
+## `lyra-commit-card`
+
+A compact commit summary (subject, author/time, diffstat, per-file changes) that links file rows out
+to a diff view.
+
+**Properties:** `hash: string = ''`, `message: string = ''`, `author: string = ''`, `timestamp?:
+number` (attribute: false), `files: CommitFileChange[] = []` (attribute: false), `filesCollapsed:
+boolean = true` (attribute `files-collapsed`, reflected), and `copyable: boolean = true` (reflected).
+
+**Slots:** `actions` — trailing header controls (e.g. an "open PR" button).
+
+**Events:** `lyra-file-select` (`detail: { path }`), `lyra-toggle` (`detail: { collapsed }`), and
+`lyra-copy` (`detail: { text }`, the full hash was copied).
+
+**CSS parts:** `base`, `subject`, `body`, `hash`, `meta`, `author`, `time`, `diffstat`, `additions`,
+`deletions`, `files-toggle`, `file` (carries `data-status`), `file-path`, `file-additions`,
+`file-deletions`, `copy-button`, and `actions`.
+
+## `lyra-image-viewer`
+
+A full pan/zoom raster-image viewer with labeled region highlights and opt-in region annotation, the
+landing surface for `region`-anchored citations. Distinct from `<lyra-svg-viewer>` (rendered SVG
+documents) and `<lyra-image-comparer>` (before/after slotted surfaces). Adopts `DocumentAnchorTarget`
+with `anchorKinds: ['region']` only — no text selection is bound.
+
+**Properties:** `src: string = ''`, `name: string = ''`, `alt?: string`, `fit: 'contain' | 'width' |
+'actual' = 'contain'` (reflected), `zoom: number = 1` (reflected), `rotation: 0 | 90 | 180 | 270 = 0`
+(reflected), and `annotatable: boolean = false` (reflected).
+
+**Methods:** `rotate()` advances `rotation` by 90°. `zoomIn()`, `zoomOut()`, and `resetZoom()` adjust
+the embedded zoomable-frame's zoom.
+
+**Events:** `lyra-load` (`detail: { naturalWidth, naturalHeight }`), `lyra-zoom-change` (`detail: {
+zoom }`), `lyra-rotation-change` (`detail: { rotation }`), `lyra-fit-change` (`detail: { fit }`),
+`lyra-highlight-activate` (`detail: { id }`), `lyra-annotation-create` (`detail: { anchor }`, kind
+`'region'`), `lyra-anchor-result` (`detail: { found }`), and `lyra-render-error` (`detail: { error
+}`).
+
+**CSS parts:** `base`, `toolbar`, `fit-control`, `rotate-button`, `annotate-toggle`, `frame` (the
+embedded `lyra-zoomable-frame`), `image-wrapper`, `image`, `highlight-layer`, `highlight` (carries
+`data-tone`/`data-active`), `highlight-label`, `annotation-box`, and `error`.
+
+## `lyra-transcript-feed`
+
+Live captions for an in-progress voice session: speaker-grouped entries, interim-vs-final styling
+with in-place upgrades keyed by `id`, and a stick-to-bottom auto-scroll with release, the same
+`follow`/`lyra-follow-change` contract `<lyra-terminal>` uses. Live captions only — recorded-media
+transcript sync is a separate concern.
+
+**Properties:** `entries: LyraTranscriptEntry[] = []` (attribute: false), `follow: boolean = true`
+(reflected), `showTimestamps: boolean = false` (attribute `show-timestamps`), `formatTimestamp?:
+(epochMs: number) => string` (attribute: false), `maxRenderedEntries: number = 0` (attribute
+`max-rendered-entries`), `label: string = ''` — accessible name for the `role="log"` region
+(default: the localized `transcriptFeedLabel`), and `accessibleLabel: string | null = null`
+(attribute `aria-label`) — overrides the log's computed accessible name, winning over `label` and
+the localized default; attribute-reflects from a host-level `aria-label`.
+
+**Methods:** `scrollToBottom()` re-engages `follow` and scrolls to the latest entry.
+
+**Slots:** `empty` — custom empty state (default: the localized "No transcript yet").
+
+**Events:** `lyra-follow-change` — `detail: { following }`, fires on every `follow` transition.
+
+**CSS parts:** `base` (the scroll container), `log` (the `role="log"` region wrapping final entries
+only), `entry`, `speaker` (omitted for a row repeating the previous row's speaker), `text`
+(`dir="auto"`), `timestamp` (only while `show-timestamps`), `interim` (present alongside `entry` on
+an interim row), `jump-button` (shown only while `follow` is `false`), and `empty`.
+
+## `lyra-av-player`
+
+An audio/video player built on a native `<audio>`/`<video>` element, plus a cue transcript synced to
+`currentTime`, `time-range` anchor/highlight support, an optional dependency-free waveform (peaks
+in, no in-component decoding), and playback-rate control. Owns recorded-media transcript sync —
+distinct from `<lyra-transcript-feed>` (live captions for an in-progress voice session) and
+`<lyra-playback>` (an index stepper, no media). Adopts `DocumentAnchorTarget` with
+`anchorKinds: ['time-range']` only — no text selection is bound. The transcript virtualizes through
+`<lyra-virtual-list>` the same way `lyra-pdf-viewer` virtualizes pages.
+
+**Properties:** `src: string = ''`, `name: string = ''`, `kind?: 'audio' | 'video'` (attribute:
+false auto-detection override), `mimeType: string = ''` (attribute `mime-type`), `poster: string =
+''`, `loop: boolean = false`, `muted: boolean = false`, `preload: 'none' | 'metadata' | 'auto' =
+'metadata'`, `playbackRate: number = 1` (attribute `playback-rate`, reflected), `rates: number[] =
+[0.75, 1, 1.25, 1.5, 2]` (attribute: false), `cues: LyraAvCue[] = []` (attribute: false), `peaks:
+number[] = []` (attribute: false), and `tracks: LyraAvTrack[] = []` (attribute: false).
+`LyraAvCue = { id, start, end?, text, speaker? }`; `LyraAvTrack = { src, kind: 'subtitles' |
+'captions' | 'descriptions', srclang, label, default? }`.
+
+**Methods:** `play()`, `pause()`, and `toggle()` proxy the native media element. `seek(seconds)`
+sets `currentTime` and forces an immediate `lyra-time-change`. `search(query)` resolves the match
+count; `searchNext()`/`searchPrevious()` wrap; `clearSearch()` resets.
+
+**Events:** `lyra-play`, `lyra-pause`, `lyra-load` (`detail: { duration, kind }`), `lyra-time-change`
+(`detail: { currentTime }`, throttled to at most 4/s while playing plus one extra per `seek()`),
+`lyra-rate-change` (`detail: { rate }`), `lyra-cue-change` (`detail: { id }`, `id` is `null` when no
+cue is active), `lyra-highlight-activate` (`detail: { id }`), `lyra-anchor-result` (`detail: {
+found }`), `lyra-search-change` (`detail: { query, matchCount, activeIndex }`), and
+`lyra-render-error` (`detail: { error }`).
+
+**CSS parts:** `base`, `media` (the native `<audio>`/`<video>` element), `toolbar`, `rate-select`,
+`timeline` (click-to-seek and arrow-key seeking), `timeline-marker` (one per `time-range` highlight;
+`data-tone`, `data-active`), `transcript` (the `<lyra-virtual-list>` itself), `cue` (`aria-current`,
+`data-match`, `data-active-match`), `cue-time`, `cue-speaker`, `cue-text`, and `error`.
+
+## `lyra-test-results`
+
+A pass/fail suite summary with per-status counts, status filter toggles, and per-test rows whose
+failures auto-expand by default and can host rich slotted detail (e.g. a diff or code block)
+alongside the plain failure message.
+
+**Properties:** `suites: TestSuiteResult[] = []` (attribute: false), `statusFilter: TestStatus[] =
+[]` (attribute: false), and `autoExpandFailures: boolean = true` (attribute
+`auto-expand-failures`).
+
+**Slots:** `detail-{testId}` — rich failure detail for that test, rendered after its plain message
+text once the row is expanded.
+
+**Events:** `lyra-test-select` (`detail: { suiteId, testId }`, a test row's name was activated),
+`lyra-filter-change` (`detail: { statuses }`, the status-set filter changed), and `lyra-toggle`
+(`detail: { id, expanded }`, a row's failure detail was expanded/collapsed).
+
+**CSS parts:** `base`, `summary` (the status-count strip), `count` (carries `data-status`), `filter`,
+`filter-toggle` (carries `data-status`/`aria-pressed`), `suite`, `suite-header`, `test` (carries
+`data-status`), `test-status`, `test-name`, `test-duration`, `test-expand-toggle`, `failure`
+(hidden while collapsed), and `failure-message`.
+
+## `lyra-env-list`
+
+A masked key/value list for environment variables and secrets, with per-row reveal and copy.
+Masking is presentational, not a security boundary: the real value sits in a DOM property
+regardless of mask state.
+
+**Properties:** `entries: EnvEntry[] = []` (attribute: false), `revealable: boolean = true`
+(reflected), `copyable: boolean = true` (reflected), and `label: string = ''`.
+
+**Events:** `lyra-reveal-change` (`detail: { name, revealed }`) and `lyra-copy` (`detail: { text }`,
+the real unmasked value).
+
+**CSS parts:** `base` (the `<dl>` root), `name` (the `<dt>` text), `value-cell` (the `<dd>` wrapping
+an entry's value text and buttons), `value` (carries `data-masked`), `reveal-button`, and
+`copy-button`.
+
+## `lyra-handoff-divider`
+
+A labeled semantic separator marking control transfer between agents in a transcript ("Transferred
+to Research Agent"), with an optional agent avatar. Purely presentational: no events, no
+interactivity, no restore semantics. The computed label is announced once, on first connect,
+through an internal `<lyra-live-region>`.
+
+**Properties:** `agent: string = ''`, `fromAgent: string = ''` (attribute `from-agent`), and `label:
+string = ''`.
+
+**Slots:** `avatar` — the incoming agent's `<lyra-avatar>` (or icon), hidden entirely while empty.
+
+**CSS parts:** `base` (the separator root, `role="separator"`), `line` (each of the two flanking
+rules), `chip` (the visual `aria-hidden` chip wrapping the avatar and label), `avatar` (wrapper
+around the `avatar` slot, only shown while the slot has content), and `label`.
+
+## `lyra-chat-viewport`
+
+The transcript scroll container: owns stick-to-bottom behavior while an answer streams, the "jump to
+latest" pill, and the unread divider. Two supported content shapes, auto-detected: ordinary element
+children (typically `lyra-chat-message`s — *slotted mode*), or exactly one `lyra-virtual-list`
+(*virtual mode*, detected via `instanceof`). In virtual mode this component defers all scrolling to
+the slotted list's own `scrollToIndex()`. Follow/release state machine: while `follow` is engaged,
+content growth re-scrolls to the end; release happens only on a user-intent gesture (wheel,
+touchmove, scrollbar-drag, or PageUp/ArrowUp/Home while the log region has focus) that leaves the
+view more than `bottomThreshold` from the end — a scroll caused by this component's own programmatic
+scrolling, or by a layout shift, never releases it. Reaching the bottom again by any means re-engages
+`follow`.
+
+**Properties:** `follow: boolean = true` (reflected) — component-managed stick-to-bottom state,
+host-writable: setting `true` scrolls to the end and re-engages following, setting `false` releases
+it. `bottomThreshold: number = 24` (attribute `bottom-threshold`) — px distance from the end still
+counted as "at bottom." `unreadStartIndex: number | null = null` (attribute `unread-start-index`) —
+index of the first unread item (element-child index in slotted mode, `items` index in virtual mode);
+`null` disables both the divider and the pill's unread count. `label: string = ''` — accessible name
+for the log region, defaults to the localized `chatViewportLabel`. `accessibleLabel: string | null =
+null` (attribute `aria-label`) — host `aria-label`, forwarded to the internal `role="log"` element
+(an `aria-label` left on the host itself names nothing, since the log role lives inside the shadow
+root); wins over `label` and the localized default.
+
+**Methods:** `scrollToBottom(options?)` — scrolls to the end and re-engages `follow`; default
+`smooth`, forced to `auto` under `prefers-reduced-motion`. `scrollToUnread(options?)` — scrolls the
+unread divider to the top of the view, resolving `false` when `unreadStartIndex` is `null`/out of
+range; does not re-engage `follow`.
+
+**Events:** `lyra-follow-change` — `detail: { following }`, fired whenever `follow` flips (user
+scroll-up release, or reaching the bottom again). Never fired for the initial mount state.
+
+**Slots:** default — the transcript: ordinary element children, or exactly one `lyra-virtual-list`.
+
+**CSS parts:** `base` (the positioning root), `scroll` (the scroll container, `role="log"`,
+`tabindex="0"`; in virtual mode it stops scrolling itself but keeps the role), `content` (the
+slotted-content wrapper the growth observers watch), `jump-pill` (the built-in jump-to-latest button,
+absent while `follow` is engaged), `unread-divider` (the "New messages" separator, slotted mode
+only).
+
+Renders no messages and computes no unread state itself — the host supplies `unreadStartIndex`; no
+virtualization of its own (`lyra-virtual-list`); not a generic overflow surface (`lyra-scroller`); no
+message semantics (`lyra-chat-message`).
+
+```html
+<lyra-chat-viewport unread-start-index="12" @lyra-follow-change=${(e) => console.log(e.detail.following)}>
+  <lyra-chat-message role="user">…</lyra-chat-message>
+  <lyra-chat-message role="assistant" status="streaming">
+    <lyra-streaming-text streaming .content=${partial}></lyra-streaming-text>
+  </lyra-chat-message>
+</lyra-chat-viewport>
+<lyra-chat-composer status="streaming"></lyra-chat-composer>
+```
+
+## `lyra-suggestion-chips`
+
+Starter prompts (empty thread) and follow-up suggestions (after a response) as a horizontally
+scrollable chip row; activation hands the prompt to the host, which decides whether to compose it
+into an input or send it directly. Never writes into a composer or sends anything itself.
+Streaming-friendly: chips render through a keyed `repeat()` on `id`, so replacing follow-ups
+mid-conversation preserves focus on any chip whose `id` survives.
+
+**Properties:** `suggestions: ChatSuggestion[] = []` (attribute: false, each `{ id, label, detail? }`
+— `detail` is an optional secondary line). Empty renders nothing at all. `wrap: boolean = false`
+(reflected) — wraps into multiple rows instead of a single horizontally scrollable line. `label:
+string = ''` — accessible name for the group, defaults to the localized `suggestionsLabel`.
+
+**Events:** `lyra-suggestion-select` — `detail: { id, label }`.
+
+**CSS parts:** `base` (the labeled group), `chip` (each suggestion button), `chip-label` (the primary
+text), `chip-detail` (the secondary line, only rendered when `detail` is set).
+
+Keyboard: roving tabindex across chips; ArrowLeft/ArrowRight (direction-aware) plus Home/End;
+Enter/Space activate. Renders inside an internal `lyra-scroller` (`orientation="horizontal"`,
+`hide-scrollbar`) unless `wrap` is set.
+
+```html
+<lyra-suggestion-chips .suggestions=${followUps}
+  @lyra-suggestion-select=${(e) => (composer.value = e.detail.label)}></lyra-suggestion-chips>
+<lyra-chat-composer></lyra-chat-composer>
+```
+
+## `lyra-thread-list`
+
+The conversation sidebar: a grouped, searchable list of chat sessions with pin/archive/delete/rename
+affordances. *Data mode* (non-empty `threads`, or empty `threads` with nothing slotted) renders every
+row as a `lyra-conversation-item` inside an internal `lyra-virtual-list` — virtualized by
+construction, scroll position and per-row state survive a `threads` replacement; zero rows renders
+the built-in empty state. *Slotted mode* (empty `threads` *and* real slotted content) renders
+host-supplied `lyra-conversation-item`s from the default slot as-is: no grouping, virtualization, or
+row actions in that mode. No thread CRUD or persistence — every mutation
+(`lyra-thread-pin`/`-archive`/`-delete`/`-rename`) is a controlled event carrying the *requested* new
+state; the host mutates `threads`.
+
+**Properties:** `threads: ChatThread[] = []` (attribute: false, each `{ id, title, excerpt?,
+timestamp?, pinned?, archived? }`). `activeId: string = ''` (attribute `active-id`) — data mode:
+marks the matching row `active`/`aria-current` and scrolls it into view. `searchable: boolean =
+false` (reflected) — shows the built-in search field. `filter?: (thread, query) => boolean`
+(attribute: false) — overrides the default case-insensitive `title` + `excerpt` substring match.
+`grouping: 'date' | 'none' = 'date'` — data mode: bucket rows under localized date headers
+(Pinned/Today/Yesterday/Previous 7 days/Previous 30 days/one bucket per month/Archived), or a flat
+list. `rowActions: ThreadRowAction[] = []` (attribute: false, each `'pin' | 'archive' | 'delete'`) —
+data mode only: built-in icon buttons rendered into each row's `actions` slot. `showArchived: boolean
+= false` (attribute `show-archived`, reflected) — data mode: include `archived` threads (in their own
+trailing group). `editable: boolean = true` (reflected) — forwarded to each data-mode row's inline
+rename. `label: string = ''` — accessible name for the list region, defaults to the localized
+`threadListLabel`.
+
+**Slots:** default — slotted mode only: host-supplied `lyra-conversation-item`s, rendered in order.
+`empty` — replaces the built-in empty state.
+
+**Events:** (data mode; slotted mode only ever fires `lyra-filter-change`) `lyra-select` (`detail: {
+id }`), `lyra-thread-pin` (`detail: { id, pinned }` — the requested new state), `lyra-thread-archive`
+(`detail: { id, archived }`), `lyra-thread-delete` (`detail: { id }`, no built-in confirmation),
+`lyra-thread-rename` (`detail: { id, title }`, re-emitted from the row's `lyra-rename`),
+`lyra-filter-change` (`detail: { text, matchCount }`).
+
+**CSS parts:** `base`, `search`/`search-input` (the search field wrapper and `<input
+type="search">`), `list` (the list region), `empty`, `row-action` (a built-in pin/archive/delete icon
+button), `pin-glyph` (the small pin indicator on a pinned row), `group-header`/`row` (exported from
+the internal `lyra-virtual-list`).
+
+```html
+<lyra-thread-list
+  searchable
+  .threads=${threads}
+  active-id=${activeThreadId}
+  .rowActions=${['pin', 'archive', 'delete']}
+  @lyra-select=${(e) => openThread(e.detail.id)}
+></lyra-thread-list>
+```
+
+Composed with `lyra-split` (or `lyra-app-rail` + `lyra-responsive-panel`): thread-list in the start
+pane driving `activeId`, `lyra-chat-viewport` + `lyra-chat-composer` in the main pane.
+
+## `lyra-confirm-bar`
+
+An inline, non-modal approve/deny block for one proposed action — the in-flow sibling of
+`lyra-tool-approval-dialog` for confirmations that should sit in the transcript instead of hijacking
+focus. Same `lyra-approve`/`lyra-deny` event shapes as the dialog, and the same
+`toolApprovalHeading`/`toolApprovalArgsLabel`/`deny`/`approve` localization keys, so the two always
+translate in lockstep. Non-modal by contract: no focus trap, no scroll lock, no Escape/backdrop
+semantics, and it never steals focus when it appears in the transcript. DOM and tab order put Deny
+before Approve. On activation, focus moves synchronously to `[part="status"]` (an always-rendered,
+`tabindex="-1"` element) before the Deny/Approve buttons unmount.
+
+**Properties:** `toolName: string = ''` (attribute `tool-name`) — drives the default heading through
+the existing `toolApprovalHeading`/`toolApprovalGenericTool` dialog keys. `heading: string = ''` —
+free-form heading override for non-tool proposals; wins over `toolName`. `args: unknown = undefined`
+(attribute: false) — shown read-only inside a collapsed `lyra-details` + `lyra-json-viewer` when
+defined. `decision: 'approved' | 'denied' | null = null` (reflected) — decided state, set by the
+component on activation and host-writable (an externally-resolved decision renders identically but
+emits nothing). `tone: 'neutral' | 'danger' = 'neutral'` (reflected).
+
+**Slots:** default — supplementary body content between the heading and the actions (e.g. a
+`lyra-diff-view`). `footer` — extra content at the start of the action row.
+
+**Events:** `lyra-approve` (`detail: { args }` — the `args` prop as-is, identical shape to
+`lyra-tool-approval-dialog`), `lyra-deny` (no detail, identical to the dialog).
+
+**CSS parts:** `base` (`role="group"`), `heading`/`tool-name`, `body`, `args` (the
+details/json-viewer wrapper, only rendered when `args` is defined), `footer`, `deny-button`,
+`approve-button` (named identically to the dialog's parts), `status` (the decided-state text, always
+present in the DOM as a focus landing spot).
+
+```html
+<lyra-tool-call-chip status="pending"></lyra-tool-call-chip>
+<lyra-confirm-bar tool-name="run_shell" .args=${args}
+  @lyra-approve=${(e) => run(e.detail.args)} @lyra-deny=${() => cancel()}
+></lyra-confirm-bar>
+```
+
+## `lyra-checkpoint`
+
+An inline conversation restore point: a labeled marker between messages whose Restore affordance
+confirms inline, then hands the host a `lyra-restore` event. This component persists and restores
+nothing itself — host state in, events out. Not a handoff or plain rule
+(`lyra-handoff-divider`/`lyra-divider`); not branch navigation across regenerated variants
+(`lyra-branch-picker`); not recorded-run playback (`lyra-playback`).
+
+**Properties:** `checkpointId: string = ''` (attribute `checkpoint-id`) — opaque id echoed in the
+`lyra-restore` event detail. `label: string = ''` — checkpoint name; the localized `checkpointLabel`
+fallback renders while empty. `timestamp?: Date | string` (attribute: false) — optional creation
+time, rendered as `<time datetime>`, default `hour:minute` in `effectiveLocale`; invalid strings are
+treated as unset. `formatTimestamp?: (date: Date) => string` (attribute: false) — overrides the
+default rendering. `restorable: boolean = true` — when `false`, renders a plain marker with no
+button. `confirmRestore: boolean = true` (attribute `confirm-restore`) — gates the event behind an
+inline confirm step; a string-aware converter parses `confirm-restore="false"` correctly from plain
+HTML. `restoring: boolean = false` (reflected) — host-set busy state: the Restore button becomes
+`aria-disabled="true"` with a spinner beside the localized "Restoring…" text.
+
+**Slots:** default — optional supplemental content under the marker row (e.g. what changed since
+this point).
+
+**Events:** `lyra-restore` — `detail: { checkpointId, label }`; fired on Restore activation, after
+the inline confirm when `confirmRestore` is on. Not cancelable.
+
+**CSS parts:** `base` (`role="group"`), `line` (each of the two flanking rules), `icon` (bookmark
+glyph), `label`, `timestamp`, `restore-button` (only while `restorable`), `confirm-group`,
+`confirm-prompt`, `confirm-button`, `cancel-button`.
+
+**Themeable custom properties:** `--lyra-checkpoint-spin-duration` (default `1s`) — duration of one
+restoring-spinner rotation; stopped under reduced motion.
+
+```html
+<lyra-checkpoint checkpoint-id="ck_18" label="Before refactor" .timestamp=${t}
+  @lyra-restore=${(e) => restoreTo(e.detail.checkpointId)}></lyra-checkpoint>
+```
+
+## `lyra-usage-badge`
+
+Compact, static resource strip for one message or run — tokens in/out, cost, latency — with a
+hover/focus tooltip breakdown. Purely formatting: computes no counts, rates, or prices; every segment
+is independently optional, and with nothing set, nothing renders at all (not even a focusable shell).
+The tooltip reuses `lyra-tool-call-chip`'s hover/focus/Escape/`aria-describedby` contract wholesale.
+Not `lyra-context-meter` (occupancy of a fixed capacity); not `lyra-generation-status` (live, with a
+Stop button) — this is static after the fact.
+
+**Properties:** `tokensIn?: number` (attribute `tokens-in`) — input tokens, normalized to a
+non-negative integer, locale-formatted; segment omitted while unset/non-finite. `tokensOut?: number`
+(attribute `tokens-out`) — same rules. `costText: string = ''` (attribute `cost-text`) —
+pre-formatted cost (e.g. `"$0.012"`), rendered verbatim. `latencyMs?: number` (attribute
+`latency-ms`) — formatted with the shared duration algorithm (`820 -> "820ms"`, `1500 -> "1.5s"`).
+`compact: boolean = false` — token counts render via `Intl.NumberFormat` `notation: 'compact'`; the
+tooltip always shows full grouped figures.
+
+**Slots:** default — extra rows appended below the built-in tooltip breakdown (e.g. cache-read
+tokens); the visible strip itself is prop-driven only.
+
+**CSS parts:** `base` (a focusable non-button `role="group"`, only rendered while at least one
+segment or the default slot has content), `tokens-in`, `tokens-out`, `cost`, `latency`, `tooltip`.
+
+```html
+<lyra-chat-message role="assistant" status="sent">
+  <lyra-usage-badge slot="badges" tokens-in="1204" tokens-out="386"
+    cost-text="$0.012" latency-ms="2350"></lyra-usage-badge>
+  <lyra-markdown .content=${answer}></lyra-markdown>
+</lyra-chat-message>
+```
+
+## `lyra-browser-frame`
+
+Presentational "agent computer" viewport: a screenshot/frame stream (or slotted live media), a
+read-only URL display, action-ping overlays, and take-over/stop affordances. No automation transport
+(no CDP/WebRTC/WebSocket) and no input relay — take-over is an event; the host swaps in its own
+interactive element (e.g. an iframe). No replay scrubber (compose `lyra-playback` driving `frame-src`
+from a screenshot array); no console/network drawers (compose `lyra-terminal`/`lyra-json-viewer`); no
+pan/zoom of the frame content (slot the image/video inside a `lyra-zoomable-frame` instead, though
+the pings overlay assumes the unzoomed content box in that composition).
+
+**Properties:** `frameSrc: string = ''` (attribute `frame-src`) — image/MJPEG stream URL rendered as
+an `<img>` (safe-URL-gated via `safeMediaSrc`); ignored once the default slot has content. `url:
+string = ''` — address shown read-only in the toolbar (`dir="ltr"`, truncating, full value in
+`title`). `status: 'idle' | 'connecting' | 'streaming' | 'stalled' = 'idle'` (reflected). `controller:
+'agent' | 'user' = 'agent'` (reflected) — who is driving; switches the take-over button's label.
+`pings: BrowserPing[] = []` (attribute: false, each `{ id, x, y, kind: 'click' | 'type' | 'scroll' |
+'move' }` — `x`/`y` are percent (0–100) of the frame's `object-fit: contain` content box,
+letterboxing-aware). `controls: boolean = true` — render the built-in take-over/stop buttons.
+
+**Slots:** default — host-owned live element (e.g. `<video>` or an interactive `<iframe>`), replacing
+the `frame-src` image. `actions` — extra toolbar controls.
+
+**Events:** `lyra-take-over` — `detail: { controller }`, the *requested* controller (`'user'` when
+"Take over" is pressed, `'agent'` when "Hand back" is). `lyra-stop` — stop the agent's browser
+session, no detail.
+
+**CSS parts:** `base` (`role="group"`), `toolbar`, `url`, `status` (`role="status"`),
+`controller-badge`, `actions`, `take-over-button`, `stop-button`, `viewport`, `frame` (the
+`frame-src` `<img>`, absent once the default slot is populated), `ping` (one action-ping marker,
+carries `data-kind`).
+
+**Themeable custom properties:** `--lyra-browser-frame-aspect-ratio` (default `16 / 9`) — the
+viewport's aspect ratio.
+
+```html
+<lyra-browser-frame status="streaming" url="https://example.com" .pings=${pings}
+  @lyra-take-over=${(e) => setController(e.detail.controller)} @lyra-stop=${() => stopSession()}
+></lyra-browser-frame>
+```
+
+## `lyra-artifact-panel`
+
+Shell around one agent-generated artifact: a title/kind header, a preview↔code toggle, version
+navigation with restore, a streaming indicator, and built-in copy/download actions. Renders none of
+the artifact itself — content is slotted. No content rendering of its own (slots own it), no
+dialog/dock chrome (compose `lyra-dialog`/`lyra-dock-panel`/`lyra-split`), no version storage or
+diffing (host state; diffs via `lyra-diff-view`), no code editing (`lyra-code-editor`).
+
+**Properties:** `label: string = ''` — the artifact's title, shown in the header. `kind: string = ''`
+— a short kind label (e.g. `document`, `code`), shown as a badge next to `label`. `view: 'preview' |
+'code' = 'preview'` (reflected) — which slot is currently visible. `versions: ArtifactVersion[] = []`
+(attribute: false, each `{ id, label? }`) — the artifact's version history, oldest first; the last
+entry is the latest version. `activeVersionId: string | null = null` (attribute
+`active-version-id`) — the currently viewed version's id, or `null` for "the latest version."
+`streaming: boolean = false` (reflected) — whether the artifact is still being generated; sets
+`aria-busy` on the body and shows a text indicator (not animated, so it stays legible under reduced
+motion). `copyText: string = ''` (attribute `copy-text`) — the text copied to the clipboard by the
+copy button; empty hides the button. `downloadSrc: string = ''` (attribute `download-src`) — the
+download URL, sanitized through `safeMediaSrc()`; empty hides the button. `downloadName: string =
+''` (attribute `download-name`) — the suggested filename reported in the `lyra-download` event
+detail.
+
+**Slots:** default — preview-view content (markdown/html-viewer/browser-frame/image). `code` —
+code-view content (typically a `lyra-code-block`); the preview/code toggle only renders once this
+slot has assigned content. `actions` — extra header controls, rendered between the version
+navigation and the built-in copy/download buttons.
+
+**Events:** `lyra-view-change` (`detail: { view }`), `lyra-version-change` (`detail: { versionId }`,
+fired when the previous/next navigation moves to a different version), `lyra-restore` (`detail: {
+versionId }`, fired by the restore-this-version button; mutates nothing itself), `lyra-copy`
+(`detail: { text }`, after a best-effort clipboard write), `lyra-download` (`detail: { filename,
+src? }`, with the sanitized download URL).
+
+**CSS parts:** `base`, `header`, `label`, `kind`, `view-toggle` (rendered only once the `code` slot
+has content), `view-button` (carries `data-view="preview"` or `data-view="code"`), `version-nav`
+(rendered only once `versions` is non-empty), `version-previous`, `version-next`, `version-position`
+(the "Version N of M" text), `restore-button` (rendered only while the active version isn't the
+latest), `actions`, `copy-button` (rendered only while `copyText` is non-empty), `download-button`
+(rendered only while `downloadSrc` is non-empty), `body`, `streaming-indicator` (rendered only while
+`streaming`).
+
+```html
+<lyra-artifact-panel label="report.md" kind="document" .versions=${versions}
+  @lyra-restore=${(e) => restoreVersion(e.detail.versionId)}>
+  <lyra-markdown .content=${markdown}></lyra-markdown>
+  <lyra-code-block slot="code" language="markdown" .code=${markdown}></lyra-code-block>
+</lyra-artifact-panel>
+```
+
+## `lyra-widget-renderer`
+
+Renders an agent-streamed declarative JSON widget tree through an allowlisted `type -> lyra tag`
+registry: safe generative UI with exactly one action event out. A mapped node's real element is
+created via `document.createElement()` with every prop assigned as a plain JS property (never
+`setAttribute`, never `innerHTML`), and reused by key across a re-resolve so a mapped widget's own
+internal state (an open `<details>`, focus, scroll position) survives a streamed `tree` update.
+Built-in `row`/`col`/`text` structural nodes render through ordinary nested templates instead. Not a
+form runtime (no input/select/form types in the default registry), no expression language or
+data-binding, no remote widget/schema fetching, and it never renders arbitrary HTML or navigates (no
+`href` props are allowlisted anywhere).
+
+**Exported types:** `WidgetNode { type: string; id?: string; props?: Record<string, unknown>;
+children?: (WidgetNode | string)[]; slot?: string; actionId?: string; payload?: unknown }` — `id` is
+a stable reconciliation key (falling back to a structural path), `slot` is honored only when the
+parent type allowlists it, `actionId` arms the type's declared action trigger, and `payload` is
+echoed back in `lyra-widget-action`.
+
+**Properties:** `tree: WidgetNode | null = null` (property only) — the declarative widget tree to
+render; `null` renders an empty base. `registry?: WidgetTypeRegistry` (attribute: false) — a
+per-instance override of the module-level default registry.
+
+**Registry module (`widget-renderer/registry.js`):** `registerWidgetType(type, def)` registers (or
+overwrites) a type in the default registry; `def: WidgetTypeDefinition { tag?: string; props?:
+Record<string, 'string' | 'number' | 'boolean'>; forcedProps?: Record<string, unknown>; slots?:
+string[]; action?: { event: string } }` — `tag` is resolved prefix-aware, `props` is a prop allowlist
+(a prop absent here, or whose runtime type doesn't match, is silently skipped — never assigned),
+`forcedProps` always apply and are never overridable by `WidgetNode.props`, `slots` allowlists child
+`slot` names (a disallowed one renders unslotted rather than being dropped), and `action.event` is
+the native/custom DOM event that arms `lyra-widget-action` when a node also sets `actionId`.
+`getDefaultWidgetTypeRegistry()` returns the module-level registry `registerWidgetType()` writes to.
+
+**Default registry** (populated by the side-effect entry's `registerDefaultWidgetTypes()`): `text`
+(plain text node), `row`/`col` (internal flex wrappers; props `gap: 's'|'m'|'l'`, `align:
+'start'|'center'|'end'|'stretch'`, `justify: 'start'|'center'|'end'|'between'`), `card` →
+`lyra-card` (`appearance`), `badge` → `lyra-badge` (`variant`), `button` → `lyra-button` (`variant`,
+`appearance`, `size`, `disabled`, `loading`; action: `click`), `stat` → `lyra-stat` (`label`,
+`value`, `unit`, `variant`, `caption`, `sub`), `result-card` → `lyra-result-card` (`title`),
+`result-field` → `lyra-result-field` (`label`, `value`), `markdown` → `lyra-markdown` (`content`;
+forced `{ sanitize: true }`), `image` → `lyra-media-card` (`src`, `alt`, `filename`; forced `{ kind:
+'image' }`).
+
+**Events:** `lyra-widget-action` — `detail: { actionId, payload }`, the single bubbling action
+channel. `lyra-render-error` — `detail: { error }`, the root value was structurally unusable
+(non-object, or the depth/size caps made it empty).
+
+**CSS parts:** `base` (the root wrapper, `display: contents`), `row`, `col`, `text` (built-in
+structural nodes only — a mapped lyra component exposes its own parts instead).
+
+Caps: depth 32, 5,000 nodes — excess is skipped with a deduped `console.warn` per type/prop per
+instance. Reconciliation is keyed by `id ?? structural path`, so a streamed re-send patches in
+place and user state (an open `<details>`, focus, scroll) survives.
+
+```ts
+registerWidgetType('sparkline', { tag: tag('sparkline'), props: { data: 'string' } });
+```
+```html
+<lyra-widget-renderer .tree=${msg.widget}
+  @lyra-widget-action=${(e) => sendToAgent(e.detail.actionId, e.detail.payload)}
+></lyra-widget-renderer>
+```
+
+**Optional peer deps:** none new — the default-registry entry directly imports the eight mapped
+components (`markdown` keeps its own `marked`/`dompurify` optional-peer fallback). A host wanting a
+leaner dependency graph registers a custom registry (via the `registry` property) and imports only
+the components it maps.
+
+## `lyra-voice-picker`
+
+A TTS voice selector over a host-supplied `catalog`, mirroring `lyra-model-select`'s
+closed-dropdown/free-text-combobox dual mode, stale-value handling, and form-association verbatim
+(see that section for the full mode-switching contract this one shares), extended with a
+TTS-agnostic preview affordance. Preview is event-first: `lyra-preview-request` always fires first
+and is cancelable — left un-prevented, a `previewUrl` plays through one internal native `<audio>`
+(validated by `safeMediaSrc()` first); `preventDefault()` or no URL leaves playback to the host's own
+TTS. Requesting the same voice while it's already playing internally stops it instead of
+re-requesting; requesting a different voice switches. Does not synthesize speech, fetch catalogs, or
+persist selection; not a persona picker; `lyra-model-select` stays for LLMs.
+
+**Exported types:** `LyraVoiceCatalogEntry { id: string; label: string; language?: string;
+description?: string; previewUrl?: string }` — `language`/`description` render as a quiet
+`[part="option-meta"]` second line. `LyraVoiceCatalog = string[] | LyraVoiceCatalogEntry[]` —
+homogeneous, same union contract as `LyraModelCatalog`.
+
+**Properties:** `provider: string = ''` — informational only (e.g. `'elevenlabs'`); rendered as a
+small leading badge. `catalog?: LyraVoiceCatalog` (attribute: false) — the full voice 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`. `preview:
+boolean = true` (reflected) — whether to render preview affordances at all. `label: string = ''`,
+`hint: string = ''`, `errorText: string = ''` (attribute `error-text`), `placeholder: string = ''`,
+`spellcheck: boolean = true` (string-aware converter, same as `lyra-model-select`), `autocapitalize:
+string = ''`, `autoCorrect: string = ''` (attribute `autocorrect`), `autocomplete: string = 'off'`,
+`inputMode: string = ''` (attribute `inputmode`), `enterKeyHint: string = ''` (attribute
+`enterkeyhint`), and `open: boolean = false` (reflected) — all mirror `lyra-model-select`'s
+identically-named properties.
+
+**Form association:** hand-rolled via `attachInternals()`, mirroring `lyra-model-select`: `value`
+getter/setter (the current voice id, `''` when nothing is selected), `name` (reflected), `disabled`
+(reflected), `required` (reflected — enforced via `internals.setValidity()`).
+
+**Events:** `lyra-change` — `detail: { value, inCatalog }`. `lyra-preview-request` — `detail: {
+voiceId, previewUrl? }`, cancelable. `lyra-preview-change` — `detail: { voiceId }`, internal playback
+started (`voiceId`) or stopped (`null`). Plus mirrored native `input`/`change` and re-dispatched
+`focus`/`blur` (picker-family contract, same as `lyra-model-select`).
+
+**Slots:** `hint`, `error`.
+
+**CSS parts:** `form-control-label`, `trigger` (closed-dropdown mode), `combobox`/`combobox-input`
+(free-text mode), `provider-badge`, `listbox`, `option`, `option-label`, `option-meta` (the quiet
+`language · description` second line), `option-badge` (the "not in catalog" badge on a synthetic
+stale-value row), `option-preview` (a pointer-only per-row preview icon, `tabindex="-1"`,
+`aria-hidden`), `preview-button` (the standalone, keyboard-reachable preview toggle beside the
+trigger), `expand-icon`, `empty`, `hint`, `error`.
+
+```html
+<lyra-voice-picker provider="elevenlabs" .catalog=${voices} allow-custom
+  @lyra-change=${(e) => setVoice(e.detail.value)}
+  @lyra-preview-request=${(e) => {
+    if (!e.detail.previewUrl) {
+      e.preventDefault();
+      playSample(e.detail.voiceId);
+    }
+  }}
+></lyra-voice-picker>
+```
+
+**Known gotchas:**
+- Listbox options must not contain tab-focusable controls, so preview is accessible via the
+  standalone `[part="preview-button"]` beside the trigger (previews the active option while open,
+  else the committed value) — the per-row `[part="option-preview"]` icon is a pointer-only
+  duplicate (`tabindex="-1"`, `aria-hidden="true"`).
+- `catalog` must be homogeneous — the same constraint `lyra-model-select`'s `LyraModelCatalog` union
+  documents.
+
+## `lyra-notebook-viewer`
+
+Read-only Jupyter notebook (nbformat 4.x) renderer, composing existing components per cell.
+Execution is a hard non-goal. Markdown cells render through `lyra-markdown`, code cells through
+`lyra-code-block` (using the notebook's kernel language for syntax highlighting), and raw cells as
+plain preformatted text. A code cell's `execute_result`/`display_data` outputs prefer, in order,
+`image/png`, `image/jpeg`, `image/svg+xml` (sanitized), `text/html` (sanitized), `application/json`
+(via `lyra-json-viewer`), then `text/plain`. Stream/error outputs render as plain preformatted text
+(tinted `danger` for stderr/tracebacks). Sanitizing raw HTML/SVG output markup lazy-loads the
+optional peer `dompurify`; without it, the output renders a localized notice instead of raw markup.
+Cells are virtualized through `lyra-virtual-list`. `node-path` anchors resolve `path[0]` as a cell
+index; `fragment` anchors resolve a cell's own `id`. No execution, no kernels, no editing, no
+ipywidgets.
+
+**Properties:** `src: string = ''` — URL to fetch and parse as a notebook; ignored once `notebook` is
+set. `notebook?: object | string` (property only) — an already-parsed notebook document, or its raw
+JSON text; wins over `src` and is parsed (and validated) synchronously. `name: string = ''` —
+accessible label, and matched against a `fragment` anchor's cell id. `outputCollapseLines: number =
+40` (attribute `output-collapse-lines`) — a plain-text output longer than this many lines renders
+collapsed behind a toggle; `0` disables collapsing. `maxHeight: string = ''` (attribute
+`max-height`) — once set, the notebook scrolls internally past this height. `anchorKinds` is a
+readonly `['node-path', 'fragment']` (this viewer's supported `LyraAnchor.kind` values for the
+shared anchor-target contract).
+
+**Methods:** `search(query)` resolves the match count over cell sources and text outputs — a
+matching cell counts as one match (empty/whitespace query behaves like `clearSearch()`);
+`searchNext()`/`searchPrevious()` advance/step back through matches, scrolling to and flashing the
+target cell; `clearSearch()` clears the query and matches.
+
+**Events:** `lyra-load` — `detail: { cellCount, language }`, fired once a notebook has been parsed
+and validated (`language` from `metadata.language_info.name`/`kernelspec.language`, else `''`).
+`lyra-highlight-activate` — `detail: { id }`. `lyra-search-change` — `detail: { query, matchCount,
+activeIndex }`. `lyra-render-error` — `detail: { error }`, fetching, parsing, or validating the
+notebook failed.
+
+**CSS parts:** `base` (the root scroll container), `cell` (`data-cell-type="code|markdown|raw"`,
+`data-active`), `cell-gutter` (the `In [n]`/`Out [n]` label column), `cell-source`, `outputs`,
+`output` (`data-output-type`, `data-stream`), `output-toggle`, `error`, `spinner`.
+
+**Themeable custom properties:** `--lyra-notebook-viewer-max-height` (default `none`).
+
+**Optional peer deps:** `marked`+`dompurify` (markdown cells, falls back to plain text per cell),
+`shiki` (code cells, falls back to unhighlighted), `dompurify` (HTML/SVG outputs, falls back to
+`text/plain`).
+
+```html
+<lyra-notebook-viewer .notebook=${result} max-height="30rem"
+  @lyra-load=${(e) => console.log(e.detail.cellCount, 'cells')}
+></lyra-notebook-viewer>
+```
+
+A notebook major version outside 4.0–4.5, an invalid shape, or more than 2,000 cells renders a
+localized error and fires `lyra-render-error` instead of the notebook.
+
+## `lyra-xml-viewer`
+
+Collapsible, copyable, `DOMParser`-based tree view for XML documents, mirroring `lyra-json-viewer`'s
+UX (`collapsed-depth`, `copyable`, structural-path-keyed expand state that survives a same-shape
+`xml` reassignment) adapted for XML's own node kinds: elements with attributes, text, comments, CDATA
+sections, and processing instructions. Namespace-literal: qualified names render exactly as authored,
+with no namespace-URI-aware matching. `DOMParser` never resolves external entities or DTDs, so XXE
+injection is structurally out of reach. Not `lyra-json-viewer` (JS values); not `lyra-html-viewer`
+(sanitized *rendered* HTML). No XPath/XSLT evaluation, no editing, no schema validation.
+
+**Properties:** `src: string = ''` — URL to fetch and parse; ignored once `xml` is set. `xml?:
+string` (property only) — raw XML text to parse and render; wins over `src`, and setting it parses
+synchronously. `name: string = ''` — accessible label. `collapsedDepth?: number` (attribute
+`collapsed-depth`) — elements at or beyond this nesting depth (root = 0) start collapsed. `copyable:
+boolean = false` (reflected) — shows copy-to-clipboard affordances, one for the whole document plus
+one per element. `maxHeight: string = ''` (attribute `max-height`). `anchorKinds` is a readonly
+`['node-path']` (this viewer's supported `LyraAnchor.kind` values for the shared anchor-target
+contract) — each numeric path segment is the 0-based index within the parent's *element* children,
+and an optional trailing string segment `'@attrName'` addresses one attribute.
+
+**Methods:** `search(query)` resolves the match count via a case-insensitive substring search over
+every element's tag name, attribute names/values, and own text (empty/whitespace query behaves like
+`clearSearch()`); `searchNext()`/`searchPrevious()` advance/step back through matches (wrapping);
+`clearSearch()` clears the query and matches.
+
+**Events:** `lyra-copy` — `detail: { text }`. `lyra-search-change` — `detail: { query, matchCount,
+activeIndex }`. `lyra-render-error` — `detail: { error }`, fetching or parsing failed, including a
+parse error or exceeding the node cap.
+
+**CSS parts:** `base`, `toolbar` (the whole-document copy button row, only when `copyable`),
+`copy-button` (the whole-document one, or a per-node one), `tree`, `node` (`data-active` while it's
+the resolved anchor target, `data-match`, `data-active-match`), `tag` (`data-match`), `attribute`,
+`attribute-name`, `attribute-value` (`data-match`), `text` (`data-match`), `comment`, `cdata`, `pi`,
+`toggle` (an element's expand/collapse button, hidden but present for row alignment on leaf/empty
+elements), `error`, `spinner`.
+
+**Themeable custom properties:** `--lyra-xml-viewer-max-height` (default `none`).
+
+```html
+<lyra-xml-viewer .xml=${payload} collapsed-depth="2" copyable
+  search=${query}
+></lyra-xml-viewer>
+```
+
+Node cap: 50,000 — exceeding it renders the localized `xmlViewerTooManyNodes` error instead of the
+tree.
+
+## `lyra-geojson-view`
+
+Internal document-registry bridge that fetches, validates, and renders a GeoJSON file through
+`<lyra-map>`'s `dataLayers` — not a documented public tag: excluded from the README/llms family
+tables, present in the generated manifest since a defined custom element is technically reachable.
+The document registry matches `application/geo+json` and `.geojson` filenames.
+
+Validates the parsed JSON is a `Feature`/`FeatureCollection`/bare geometry (one of `Point`,
+`LineString`, `Polygon`, `MultiPoint`, `MultiLineString`, `MultiPolygon`, `GeometryCollection`) before
+rendering; anything else renders the localized `geojsonViewInvalid` error. On success, it walks every
+coordinate to compute a bounding box and fits a `center`/`zoom` to it (a Web-Mercator-fit
+approximation weighting latitude span ~2x, with 40% padding), then hands the parsed value to
+`<lyra-map>` as a single `dataLayers` entry (`sourceId: 'lyra-geojson'`). When the optional
+`maplibre-gl` peer isn't installed, it falls back to a status line plus a `<lyra-json-viewer
+collapsed-depth="2">` of the raw value instead of the map.
+
+**Properties:** `src: string = ''` — URL to fetch and parse. `name: string = ''` — accessible label,
+used as `<lyra-map>`'s `label` and the root's `aria-label` (falling back to the localized
+`geojsonViewLabel` when unset).
+
+**Events:** `lyra-render-error` — `detail: { error }` — fetch, parse, or shape-validation failure.
+
+**CSS parts:** `base` (the root container), `status` (the feature-count status line, `role="status"`,
+shown only in the `<lyra-map>` path), `missing-library` (the missing-`maplibre-gl` callout shown
+alongside the `lyra-json-viewer` fallback), `error` (the error region, `role="alert"`), `spinner`
+(the loading status region).
+
+Registered by importing `geojson-view/geojson-view.js` directly — not part of the root barrel, the
+same as `lyra-map`/`lyra-graph`, since it depends on the same optional `maplibre-gl` peer. Remote
+resources are capped at 25 MB; exceeding it surfaces the localized `documentPreviewResourceTooLarge`
+message instead of the map.