@aceshooting/lyra-ui 5.0.0 → 5.2.0

package/llms/components/lr-gauge.md

@@ -0,0 +1,65 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/data.md — do not edit this file. -->
+
+# `lr-gauge`
+
+- **Import** `import '@aceshooting/lyra-ui/components/data/gauge/gauge.js';` (registers the tag; side-effect import)
+- **Class** `LyraGauge`, also available unregistered from `@aceshooting/lyra-ui/components/data/gauge/gauge.class.js`
+- **Family** `components/data/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-gauge`
+
+Dependency-free SVG radial, full-circle ring, or linear meter (no charting library).
+
+**Properties:**
+- `value: number = 0`
+- `min: number = 0`
+- `max: number = 100`
+- `type: 'radial'|'ring'|'linear' = 'radial'` (reflected — `radial` is a 270° sweep; `ring` is a
+  full circle that begins at 12 o'clock)
+- `label: string = ''`
+- `valueLabel?: string` (attribute: false — overrides both the visible text and the host's
+  `aria-valuetext`; an empty string is treated the same as unset and falls back to the numeric
+  `value` while removing `aria-valuetext`)
+
+**Events:** none.
+
+**Slots:** none.
+
+**CSS parts:** `base` (the `<svg>`), `track`, `fill`, `value`, `label`
+
+**Themeable custom properties:** `--lr-gauge-fill` (fill stroke, falling back to the shared
+`--lr-color-brand` token).
+
+**Optional peer deps:** none.
+
+```html
+<lr-gauge value="72" min="0" max="100" label="CPU"></lr-gauge>
+<lr-gauge type="ring" value="84" label="Coverage"
+  style="--lr-gauge-fill: var(--lr-color-success)"></lr-gauge>
+<lr-gauge type="linear" value="0.4" max="1"></lr-gauge>
+<script type="module">
+  document.querySelector('lr-gauge').valueLabel = '72°F'; // visible text and announced value
+</script>
+```
+
+**Known gotchas:**
+- setting `valueLabel` (e.g. `"72°F"`) now also sets `aria-valuetext` on the host (in addition to
+  changing the visible SVG text), so a screen reader announces your formatted string instead of the
+  raw `aria-valuenow` number; the SVG `<text part="value">`/`<text part="label">` elements are
+  `aria-hidden="true"` so they're no longer separately exposed inside the same `role="meter"` host.
+- no automatic color-threshold/variant logic is built in. Set `--lr-gauge-fill` per instance (or
+  reactively from application state) when the value should select a success/warning/danger color.
+- no documented component-specific sizing custom property; host size is fixed em values
+  (`8em`/`12em` radial, `12em`/`1.5em` linear) — resize via plain CSS `width`/`height` on the
+  element instead.
+- Divide-by-zero guarded (`max - min || 1`), and radial/linear share one component via the `type`
+  attribute.
+- non-finite `value` text remains blank, while non-finite `min`/`max` use finite default domain
+  bounds; no `NaN`/`Infinity` value leaks into the SVG geometry or ARIA attributes, and a finite
+  value is clamped into the resolved domain before being announced.
+
+---

package/llms/components/lr-generation-status.md

@@ -0,0 +1,105 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/conversation.md — do not edit this file. -->
+
+# `lr-generation-status`
+
+- **Import** `import '@aceshooting/lyra-ui/components/conversation/generation-status/generation-status.js';` (registers the tag; side-effect import)
+- **Class** `LyraGenerationStatus`, also available unregistered from `@aceshooting/lyra-ui/components/conversation/generation-status/generation-status.class.js`
+- **Family** `components/conversation/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-generation-status`
+
+A compact, ticking status readout shown alongside an in-progress AI response: elapsed time, token
+count, and token-throughput, plus a built-in Stop button. First-party invention (no Web Awesome
+equivalent). Renders as e.g. `12.3s · 340 tokens · 27 tok/s [Stop]`.
+
+**Properties:**
+- `active: boolean = false` (reflected) — whether generation is currently in progress. The
+  elapsed-time ticker (a ~1s `setInterval`) runs only while this is `true`.
+- `startedAt?: number` (attribute `started-at`) — epoch-ms timestamp of when generation began.
+  Optional — when unset, or set to a value that fails to parse as a finite number (e.g. an ISO-8601
+  date string, which `type: Number` conversion turns into `NaN`), while `active` is `true`, this
+  component captures `Date.now()` itself the moment `active` becomes `true` and counts from there
+  instead — an invalid value is treated identically to "unset", never rendered as literal `"NaNs"`.
+- `tokenCount?: number` (attribute `token-count`) — running token count so far. Omitted from the
+  readout entirely (no `tokens` segment) while unset.
+- `tokensPerSecond?: number` (attribute `tokens-per-second`) — host-computed tokens/sec figure,
+  used as-is when set. When unset, derived from `token-count`/elapsed time instead (see prose).
+- `showStop: boolean = true` (attribute `show-stop`, **not reflected**) — whether the built-in Stop
+  button renders at all. Uses a string-value-aware `ComplexAttributeConverter` (not Lit's default
+  presence-based `type: Boolean`), so a plain-HTML `show-stop="false"` content attribute correctly
+  turns it off — the literal string `"false"` maps to `false`; the attribute's mere presence with any
+  other value (or no value) maps to `true`. A Lit template can instead use a `.showStop=${false}`
+  property binding. **Caveat:** a `?show-stop=${false}` boolean-attribute *binding* still can't turn
+  it off when the attribute was never present in markup to begin with — that binding only ever
+  removes the attribute when falsy, and removing an attribute that's already absent fires no
+  `attributeChangedCallback` (see AGENTS.md); use `.showStop=${false}` or the plain
+  `show-stop="false"` string form instead.
+
+**Events:** `lr-stop` (no detail payload — `this.emit('lr-stop')` is called with no second
+argument, so `event.detail` is `null`, not `undefined`) — fired when the built-in Stop button is
+clicked.
+
+**Slots:** none.
+
+**CSS parts:** `base`, `elapsed` (always rendered, reads `"0.0s"` before the component has ever
+been active), `tokens` (only rendered when `token-count` is set), `throughput` (only rendered when
+a value is available, host-supplied or derived), `stop-button` (only rendered while `show-stop` is
+`true`)
+
+**Themeable custom properties:** shared tokens only — `--lr-color-text-quiet` (base readout and
+tokens/throughput text color), `--lr-color-text` (the elapsed segment's higher-contrast color,
+and the stop-button's icon color), `--lr-space-s` (stop-button margin), `--lr-icon-button-size`
+(stop-button min sizing, capped at `1.75rem`), `--lr-color-border`/`-surface`/`-brand`
+(stop-button border/background/hover), `--lr-focus-ring-width`/`-color`/`-offset`,
+`--lr-transition-fast`.
+
+**Optional peer deps:** none.
+
+```html
+<lr-generation-status active started-at="1732000000000" token-count="340" show-stop></lr-generation-status>
+<script type="module">
+  document.querySelector('lr-generation-status').addEventListener('lr-stop', () => {
+    controller.abort(); // stop the host's own generation
+  });
+</script>
+```
+
+This is deliberately a *different* concern than `<lr-stream-status>`: that component is about
+transport/connection health (idle/connecting/streaming/stalled, heartbeat-aware stall detection),
+while this one is a user-facing metrics readout for a generation both components' hosts typically
+already know is healthily in progress. Neither imports or depends on the other; compose both side
+by side rather than picking one. `tokens-per-second`, when supplied directly, is always used as-is;
+when omitted, this component derives a live figure from `token-count` divided by elapsed seconds,
+but only once at least one full second of elapsed time has accumulated (dividing by a sub-second
+window can produce wildly-swinging early readings, e.g. 3 tokens in 40ms reading as "75 tok/s").
+The elapsed clock is frozen, not reset, once `active` goes `false` — a static "Generated in 12.3s"
+reads better as a completed-state summary than the readout blanking out the instant generation
+ends.
+
+This readout ticks roughly once per second while active, which is exactly the kind of
+high-frequency update `<lr-live-region>`/`Announcer` exists to *prevent* from being read aloud
+verbatim — this component therefore carries no `role="status"`/`aria-live` of its own and never
+announces anything. A host that wants generation-start/-end announced should pair this with
+something that announces state *transitions* instead. The Stop button gets a normal, always-present
+`aria-label="Stop generating"`, no different from any other icon-only button in this library.
+
+**Known gotchas:**
+- `showStop` defaults to `true` and is not a reflected property. Its `ComplexAttributeConverter`
+  makes the plain content attribute `show-stop="false"` work correctly, but a `?show-stop=${false}`
+  Lit boolean-attribute *binding* still can't turn it off starting from absent markup — see the
+  property list above for the exact footgun.
+- The derived `tokens-per-second` figure only appears once `elapsedMs >= 1000`; before that, the
+  `throughput` part simply doesn't render — supply `tokens-per-second` yourself for a stable figure
+  from the very first tick.
+- The elapsed-time display is never reset to `"0.0s"` when `active` goes `false` — it freezes at
+  its last value. A host that wants a blank readout between generations must reset `started-at`/
+  `token-count` itself (or unmount/remount the element).
+- `started-at` only re-baselines the ticker at the moment it's read: mounting the component with
+  `active` already `true` but no `started-at` captures `Date.now()` at that first update, not at
+  whatever earlier instant generation may actually have begun.
+
+---

package/llms/components/lr-geojson-view.md

@@ -0,0 +1,43 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/viewers.md — do not edit this file. -->
+
+# `lr-geojson-view`
+
+- **Import** `import '@aceshooting/lyra-ui/components/viewers/geojson-view/geojson-view.js';` (registers the tag; side-effect import)
+- **Class** `LyraGeojsonView`, also available unregistered from `@aceshooting/lyra-ui/components/viewers/geojson-view/geojson-view.class.js`
+- **Family** `components/viewers/` — see `llms/index.md` for its siblings
+- **Optional peers** `maplibre-gl` — see `llms/peers.md`
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-geojson-view`
+
+Internal document-registry bridge that fetches, validates, and renders a GeoJSON file through
+`<lr-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
+`<lr-map>` as a single `dataLayers` entry (`sourceId: 'lr-geojson'`). When the optional
+`maplibre-gl` peer isn't installed, it falls back to a status line plus a `<lr-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 `<lr-map>`'s `label` and the root's `aria-label` (falling back to the localized
+`geojsonViewLabel` when unset).
+
+**Events:** `lr-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 `<lr-map>` path), `missing-library` (the missing-`maplibre-gl` callout shown
+alongside the `lr-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 `lr-map`/`lr-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.

package/llms/components/lr-graph-legend.md

@@ -0,0 +1,67 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/retrieval.md — do not edit this file. -->
+
+# `lr-graph-legend`
+
+- **Import** `import '@aceshooting/lyra-ui/components/retrieval/graph-legend/graph-legend.js';` (registers the tag; side-effect import)
+- **Class** `LyraGraphLegend`, also available unregistered from `@aceshooting/lyra-ui/components/retrieval/graph-legend/graph-legend.class.js`
+- **Family** `components/retrieval/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-graph-legend`
+
+A node-type legend for a paired `lr-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 `lr-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 `lr-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
+  `lr-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:** `lr-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:** `--lr-graph-legend-hidden-color` (default
+`var(--lr-color-text-quiet)`) — text color of a filtered-out (hidden) row's `label`/`count`,
+independent of the shared quiet-text token so a host can retint "hidden" rows without repainting
+every other quiet-text surface. Also reads `--lr-graph-cat-1` through `-8`
+(the same computed-style fallback palette `lr-graph`/`lr-word-cloud` use) plus shared tokens.
+
+**Optional peer deps:** none.
+
+```html
+<lr-graph-legend id="legend"></lr-graph-legend>
+<lr-graph id="graph" style="height:480px"></lr-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('lr-visibility-change', (e) => {
+    legend.hiddenTypes = e.detail.hiddenTypes;
+    graph.hiddenTypes = e.detail.hiddenTypes;
+  });
+</script>
+```
+
+**Known gotchas:**
+- Ships no coupling to `lr-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.
+
+---

package/llms/components/lr-graph-query-builder.md

@@ -0,0 +1,27 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/data.md — do not edit this file. -->
+
+# `lr-graph-query-builder`
+
+- **Import** `import '@aceshooting/lyra-ui/components/data/graph-query-builder/graph-query-builder.js';` (registers the tag; side-effect import)
+- **Class** `LyraGraphQueryBuilder`, also available unregistered from `@aceshooting/lyra-ui/components/data/graph-query-builder/graph-query-builder.class.js`
+- **Family** `components/data/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-graph-query-builder`
+
+Form-associated editor for a typed graph relationship/path query, including entity anchors,
+relationship and node-type filters, hop limits, validation, and saved queries.
+
+**Properties:** `value`, `label`, `labels`, `name`, `disabled`, `effectiveDisabled`, `nodeTypeOptions`,
+`relationshipTypeOptions`, `hopLimit`, `savedQueries`, `errors`, `form`, `validity`,
+`validationMessage`, `willValidate`, `checkValidity`, `reportValidity`, `formDisabledCallback`,
+`formResetCallback`, `formStateRestoreCallback`. **Events:** `lr-input`, `lr-validity-change`,
+`lr-query-run`, `lr-query-save`, `lr-query-load`, `lr-query-delete`. **Slots:** `actions`. **CSS
+parts:** `base`, `path-fields`, `start-input`, `end-input`, `relationship-picker`,
+`relationship-chips`, `node-type-picker`, `node-type-chips`, `direction`, `filter-group`,
+`min-hops`, `max-hops`, `footer`, `run-button`, `save-button`, `save-row`, `save-name-input`,
+`saved-queries`, `saved-queries-label`, `saved-list`, `saved-item`, `saved-load-button`,
+`saved-delete-button`, `saved-empty`.

package/llms/components/lr-graph.md

@@ -0,0 +1,227 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/retrieval.md — do not edit this file. -->
+
+# `lr-graph`
+
+- **Import** `import '@aceshooting/lyra-ui/components/retrieval/graph/graph.js';` (registers the tag; side-effect import)
+- **Class** `LyraGraph`, also available unregistered from `@aceshooting/lyra-ui/components/retrieval/graph/graph.class.js`
+- **Family** `components/retrieval/` — see `llms/index.md` for its siblings
+- **Optional peers** `d3-drag`, `d3-force`, `d3-selection`, `d3-zoom` — see `llms/peers.md`
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-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; 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.
+  `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` (`--lr-graph-cat-1` through `-8`, wrapping every 8 entries) > the untyped
+  `--lr-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
+  arrowhead; `color` and `dash` style the individual stroke; `label` provides a spoken-name and SVG
+  tooltip fallback but is not rendered as visible edge text; `accessibleLabel` and `description`
+  can override the spoken name and tooltip independently. A link whose `source` id doesn't resolve
+  to a real node is still dropped entirely
+  (there's no position to draw a stub from). A link whose `target` id doesn't resolve instead renders
+  as a short, dashed, non-interactive stub off `source`'s own position
+  (`[part='link'][data-dangling]`, `aria-hidden="true"`) rather than being silently dropped — e.g. for
+  a wiki-style `[[link]]` reference to a not-yet-created node. A dangling stub is excluded from
+  `d3-force`'s own simulation input and from click/keyboard interaction.
+- `width: number = 800`
+- `height: number = 600`
+- `chargeStrength: number = -300` (attribute `charge-strength` — live-reactive, see gotchas)
+- `linkDistance: number = 100` (attribute `link-distance` — live-reactive, see gotchas)
+- `minZoom: number = 0.1` (attribute `min-zoom`)
+- `maxZoom: number = 8` (attribute `max-zoom`)
+- `accessibleLabel: string | null = null` (attribute `aria-label`) — host accessible name forwarded
+  to the internal semantic SVG; when unset, the SVG uses the localized node/link-count summary
+- `seed?: number` — when set, seeds each node's initial x/y deterministically
+  (keyed by node **id**, not array index/order) instead of `forceSimulation()`'s own random start,
+  and settles the simulation synchronously instead of animating the settle (same effect
+  `prefers-reduced-motion` has, see gotchas)
+- `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:** `lr-node-click` (`detail: { id, x, y }`, where `x` and `y` are the clicked node's current
+local drawing coordinates), `lr-link-click` (`detail: { source, target,
+id? }`; the optional `id` is the stable `GraphLink.id` supplied by the caller), `lr-node-enter`/
+`lr-node-leave` (`detail: { id }`, hover start/end, suppressed while dragging/panning),
+`lr-link-enter`/`lr-link-leave` (`detail: { source, target, id? }`, same hover contract),
+`lr-node-expand` (`detail: { id }`, a node was double-activated — native `dblclick`, or two
+Enter/Space activations within 500ms — regardless of `GraphNode.expandable`), `lr-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`, `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`, `error` (`role="alert"` message shown instead of the graph when
+the optional `d3-force`/`d3-drag`/`d3-zoom`/`d3-selection` peers fail to load —
+distinct from the empty state, which means the peers loaded fine but `nodes` is 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:** `--lr-node-fill` (set inline per-node from `GraphNode.color`,
+falls back to `--lr-color-brand`) and `--lr-link-color` (set inline per-link from
+`GraphLink.color`, falling back to `--lr-color-border`); also uses `--lr-color-text` +
+`--lr-font` (label text), `--lr-focus-ring-*` (node/link `:focus-visible` outline).
+`--lr-graph-cat-1..8` (i.e. `--lr-graph-cat-1` through `--lr-graph-cat-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.
+`--lr-graph-edge-label-halo` (default `var(--lr-color-surface)`) — the legibility halo painted
+behind a drawn `[part="link-label"]` (via `paint-order: stroke`).
+`--lr-graph-focus-halo-color` (default `var(--lr-color-brand)`) — `[part="focus-halo"]` stroke.
+`--lr-graph-selected-color` (default `var(--lr-color-success)`) — selected node/link stroke.
+`--lr-graph-dimmed-opacity` (default `0.35`) — opacity of a node/link listed in
+`dimmedNodeIds`/`dimmedLinkIds`.
+`--lr-graph-hull-fill` (default `var(--lr-color-brand)`) — community hull fill/stroke color
+(overridden inline per hull from `GraphCommunity.color`).
+`--lr-graph-hull-opacity` (default `0.12`) — hull element opacity (composites fill+stroke as one).
+Under `renderer="canvas"` these five are read from computed style at paint time (there are no
+per-node elements to inherit them), so they must be set on or above the `<lr-graph>` host itself.
+
+**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 —
+install with `pnpm add d3-force d3-drag d3-zoom d3-selection`).
+
+```html
+<lr-graph style="display:block;height:500px"></lr-graph>
+<script>
+  const g = document.querySelector('lr-graph');
+  g.nodes = [
+    { id: 'a', label: 'A', accessibleLabel: 'Source document A', description: 'The source document' },
+    { id: 'b', label: 'B', description: 'The cited document' },
+  ];
+  g.links = [{
+    id: 'citation-a-b', source: 'a', target: 'b', label: 'cites',
+    accessibleLabel: 'Document A cites document B', description: 'Citation relationship',
+    directed: true, color: 'var(--lr-color-brand)', dash: [6, 3],
+  }];
+  g.addEventListener('lr-node-click', (e) => console.log(e.detail.id));
+  g.addEventListener('lr-link-click', (e) => console.log(e.detail.id, e.detail.source, e.detail.target));
+</script>
+```
+
+**Known gotchas:**
+- per-tick full re-render is expensive: every d3-force tick (up to ~300 by default,
+  continuously while dragging via `alphaTarget(0.3)`) writes node/link positions straight onto the
+  already-rendered DOM via `setAttribute()` rather than reassigning `simNodes`/`simLinks` (that
+  reassignment — and the Lit re-render/`applyInteractions()` re-scan it used to force on every tick —
+  now only happens once per structural `nodes`/`links` change). Still a noticeable cost building up
+  the initial layout or while a node is actively being dragged, just no longer once per tick on an
+  otherwise-settled graph.
+- `chargeStrength`/`linkDistance` **are** live-reactive post-mount now (retuned on the existing
+  force objects and the simulation nudged via `alpha(0.3).restart()`) — no need to also touch
+  `nodes`/`links` to see the effect.
+- `width`/`height` are also live-reactive post-mount: changing either re-centers the `forceCenter`
+  force on the new midpoint and nudges the simulation via `alpha(0.1).restart()`, in addition to
+  resizing the rendered `viewBox` — both branches apply independently, so setting `width` and
+  `chargeStrength` in the same synchronous batch retunes both, not just one.
+- zoom is bounded via `minZoom`/`maxZoom` (`d3-zoom`'s `.scaleExtent(...)`, live-reactive); pan/
+  zoom/drag are still pointer-only with no keyboard equivalent. Links (`<line part="link">`) are now
+  keyboard-operable too (`tabindex="0"`, `role="button"`, `aria-label`, Enter/Space), matching nodes.
+- while the `d3-force`/`d3-drag`/`d3-zoom`/`d3-selection` peers are resolving, the host shows a
+  `<lr-skeleton>` sized to `width`/`height` with `aria-busy="true"` — but if they fail to load
+  (not installed), it still settles into a permanently empty `<svg>` (0 nodes/0 links) plus a
+  one-time console warning, same as before; the skeleton only covers the loading window itself.
+- `GraphNode.color` is sanitized (rejects `;`/`{`/`}`) before being written into the
+  `--lr-node-fill` inline custom property, so an untrusted color string can't break out of that
+  CSS declaration.
+- `GraphLink.color` applies the same declaration-delimiter sanitization. `GraphLink.dash` is used
+  only when every entry is finite and non-negative; an empty or invalid array falls back to a solid
+  line rather than partially applying malformed SVG stroke data.
+- a structural `nodes`/`links` change now carries over each already-settled node's position (and any
+  in-progress drag) by id when rebuilding the simulation, instead of discarding every node's (x, y)
+  and re-running the whole ~300-tick random-start settle from scratch — only genuinely new ids get a
+  fresh start. Handy for a streaming/incrementally-updated graph, whose existing layout no longer
+  jumps every time a node/link is appended.
+- under `prefers-reduced-motion: reduce`, or whenever `seed` is set, the simulation converges
+  synchronously (ticked in a loop down to `alphaMin` before first paint) instead of animating over
+  ~300 rendered frames; user-initiated motion (dragging a node) is unaffected either way.
+- 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 `lr-selection-change` (`detail: { nodeIds, linkIds }`) — the host assigns them back,
+mirroring `lr-heatmap`'s `selectedCell` contract. `dimmedNodeIds: string[] = []` / `dimmedLinkIds:
+string[] = []` (both attribute: false) are the same controlled shape for dimming instead of
+selecting — the component never assigns either itself, only renders `data-dimmed` on the matching
+`[part="node"]`/`[part="link"]`, themed via `--lr-graph-dimmed-opacity` (default `0.35` — visible out
+of the box with no host styling required); a host typically computes the set from a
+`lr-node-enter`/`lr-link-enter` hover (the complement of the hovered id's neighbor set) and assigns
+it back — `lr-knowledge-graph-explorer`'s own `highlight` property is exactly this composition,
+built-in. Empty (the default) renders every node/link at full opacity, unchanged from today.
+`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. `lr-viewport-change`
+(`detail: { k, x, y }`, the live d3-zoom camera transform) fires at most once per animation frame,
+coalescing every source that can move a rendered node's screen position — a pan/zoom gesture, a
+`focusNode()`/`fit()` tween, and every simulation tick — so a consumer anchoring its own UI (e.g. a
+details popover) to a node's `getBoundingClientRect()` can re-read it from this event instead of
+polling its own `requestAnimationFrame` loop.
+
+---

package/llms/components/lr-grounding-summary.md

@@ -0,0 +1,57 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/retrieval.md — do not edit this file. -->
+
+# `lr-grounding-summary`
+
+- **Import** `import '@aceshooting/lyra-ui/components/retrieval/grounding-summary/grounding-summary.js';` (registers the tag; side-effect import)
+- **Class** `LyraGroundingSummary`, also available unregistered from `@aceshooting/lyra-ui/components/retrieval/grounding-summary/grounding-summary.class.js`
+- **Family** `components/retrieval/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-grounding-summary`
+
+Claim-level grounding scorecard for one generated answer: supported/unsupported claim counts,
+citation coverage, optional confidence, warnings, and evidence citations linking back to their exact
+spans. Consumes `GroundingAssessment` from `@aceshooting/lyra-ui/ai` directly. Pure projection +
+event conduit — never fetches or computes an assessment. Composes `lr-stat` for every numeric display
+and `lr-citation-badge` for each evidence entry.
+
+**Properties:**
+- `assessment: GroundingAssessment | null = null` (attribute: false) — **`GroundingAssessment`,
+  imported from `@aceshooting/lyra-ui/ai`** (`src/ai/types.ts`): `{ supportedClaims: number;
+  unsupportedClaims: number; coverage: number; confidence?: number; warnings?: string[] }`, where
+  `coverage` and `confidence` are 0–1 fractions. `null` renders the empty state
+- `citations: Citation[] = []` (attribute: false) — **`Citation` from `@aceshooting/lyra-ui/ai`**:
+  `{ id: string; chunkId?: string; sourceId?: string; span?: { start: number; end: number };
+  label?: string }`. Independent of `assessment`; empty omits the whole evidence section. Each entry
+  renders as an `lr-citation-badge` whose `index` is its 1-based position and whose `source-id` is
+  `citation.sourceId ?? ''`
+- `thresholds: GroundingSummaryThresholds = { high: 0.8, medium: 0.5 }` (attribute: false) —
+  `GroundingSummaryThresholds { high: number; medium: number }` (exported here), both 0–1 fractions,
+  applied to both `coverage` and `confidence`: `>= high` → `success` tone, `>= medium` → `warning`,
+  below → `danger`
+- `label: string = ''` — accessible group label; falls back to a host `aria-label`, then the
+  localized `groundingSummaryLabel`
+
+**Events:** `lr-citation-select` (`detail: CitationSelectEventDetail` from
+`@aceshooting/lyra-ui/ai` = `{ citation: Citation }`) — emitted when an evidence badge is activated.
+The inner `lr-citation-badge`'s own `lr-citation-activate` (`detail: { sourceId, index }`) still
+bubbles through unmodified; this richer event exists because a bare `sourceId`/`index` pair can't
+tell a host which exact evidence *span* to jump to.
+
+**Slots:** none.
+
+**CSS parts:** `base` (`role="group"` root), `stats` (the claim-count/coverage/confidence `lr-stat`
+row), `warnings` (omitted when there are none), `warnings-heading`, `warnings-count`,
+`warnings-list` (a `<ul>`), `warning` (one `<li>`), `evidence` (omitted when `citations` is empty),
+`evidence-heading`, `evidence-count`, `evidence-item` (badge + always-visible label/span text),
+`evidence-label` (omitted when `Citation.label` is unset), `evidence-span` (the formatted
+`Citation.span` range, omitted when unset), `empty` (shown when `assessment` is `null`).
+
+**Themeable custom properties:** shared tokens only.
+
+**Optional peer deps:** none.
+
+---

package/llms/components/lr-handoff-divider.md

@@ -0,0 +1,27 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/conversation.md — do not edit this file. -->
+
+# `lr-handoff-divider`
+
+- **Import** `import '@aceshooting/lyra-ui/components/conversation/handoff-divider/handoff-divider.js';` (registers the tag; side-effect import)
+- **Class** `LyraHandoffDivider`, also available unregistered from `@aceshooting/lyra-ui/components/conversation/handoff-divider/handoff-divider.class.js`
+- **Family** `components/conversation/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-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 `<lr-live-region>`.
+
+**Properties:** `agent: string = ''`, `fromAgent: string = ''` (attribute `from-agent`), and `label:
+string = ''`.
+
+**Slots:** `avatar` — the incoming agent's `<lr-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`.