@aceshooting/lyra-ui 6.2.0 → 7.0.0

package/llms/components/lr-widget.md

@@ -6,7 +6,7 @@
 - **Class** `LyraWidget`, also available unregistered from `@aceshooting/lyra-ui/components/layout/widget/widget.class.js`
 - **Family** `components/layout/` — see `llms/index.md` for its siblings
 - **Optional peers** none
-- **Themeable via** 14 parts, 5 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 16 parts, 5 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---
@@ -34,15 +34,16 @@ position) survives the transition.
 - `backdropInset: string = ''` (attribute `backdrop-inset`) — overrides the fullscreen backdrop's
   CSS `inset` independently from `fullscreenInset`; when empty, it follows `fullscreenInset`
 - `views: WidgetView[] = []` (attribute: false) — named alternate views for the panel body, e.g. a
-  chart/table toggle inside the same card chrome; `WidgetView { id: string; label: string; icon?:
-  TemplateResult }`. Each entry gets a header toggle button (`[part='view-toggle']`) and a
-  `<slot name="view-${id}">`. Empty (the default) renders today's single unnamed default slot as the
-  sole view, unchanged.
+  chart/table toggle inside the same card chrome; `WidgetView { id: string; label?: string; icon?:
+  TemplateResult; ariaLabel?: string }`. Each entry gets a header toggle button
+  (`[part='view-toggle']`) and a `<slot name="view-${id}">`. An icon-only view should set
+  `ariaLabel`; if both labels are omitted, the button uses `id` as a last-resort accessible name.
+  Empty (the default) renders today's single unnamed default slot as the sole view, unchanged.
 - `activeView: string = ''` (attribute: false) — the currently active view's `id`; defaults to the
   first entry of `views` (or `''` when `views` is empty). Settable directly to control the active
   view externally; also updated internally when a view toggle is clicked.
-- `accessibleLabel: string = ''` (attribute `aria-label`) — overrides the label-derived fullscreen
-  dialog name.
+- `accessibleLabel: string | null = null` (attribute `aria-label`) — overrides the label-derived
+  fullscreen dialog name.
 - `storageKey?: string` (attribute `storage-key`) — when set, persists `collapsed` to `localStorage`
   under `lr-widget:${storageKey}` and restores it on the next mount (mirrors `lr-app-rail`'s/
   `lr-table`'s identical `storage-key` pattern). Without a `storageKey` there is no persistence and
@@ -125,4 +126,9 @@ panel'`) and `widgetExpand` (default `'Expand panel'`) keys.
   to `widgetCollapse`/`widgetExpand`; the default English strings are unchanged, and `lr-dock-panel`
   itself is unaffected.
 
+**Additional API surface:**
+
+- `part="view-icon"` — Decorative icon content inside a view toggle.
+- `part="view-label"` — Visible label text inside a view toggle.
+
 ---

package/llms/components/lr-xml-viewer.md

@@ -72,10 +72,12 @@ so lowering it never squashes the chevron below its own box — the visible glyp
 the hit target follows the token, and it can never fall under the accessible minimum from this
 component's own rules.
 
-```html
-<lr-xml-viewer .xml=${payload} collapsed-depth="2" copyable
-  search=${query}
-></lr-xml-viewer>
+```ts
+const viewer = document.querySelector('lr-xml-viewer');
+viewer.xml = payload;
+viewer.collapsedDepth = 2;
+viewer.copyable = true;
+await viewer.search(query);
 ```
 
 Node cap: 50,000 — exceeding it renders the localized `xmlViewerTooManyNodes` error instead of the

package/llms/index.md

@@ -2,7 +2,7 @@
 
 # Component index
 
-256 custom elements, grouped by the source family they live in.
+268 custom elements, grouped by the source family they live in.
 
 **Reading one component.** Its reference file path is derived from the tag — no search needed:
 `llms/components/<tag>.md` (e.g. `llms/components/lr-table.md`). Each is self-contained: import
@@ -51,7 +51,7 @@ Optional peers: `llms/peers.md`. `wa-*`/`sl-*` renames: `llms/migration.md`.
 
 - `lr-sparkline` · data/sparkline/sparkline.js — a zero-dependency inline SVG trend chart.
 - `lr-stat` · data/stat/stat.js — a KPI/stat card.
-- `lr-table` · data/table/table.js — a presentational, sort/select-aware data table.
+- `lr-table` · data/table/table.js — a sort/select-aware data table.
 - `lr-pagination` · data/pagination/pagination.js — controlled, server-friendly page navigation with an editable page jump and optional item-range summary.
 - `lr-gauge` · data/gauge/gauge.js — a radial, full-circle ring, or linear meter.
 - `lr-word-cloud` · data/word-cloud/word-cloud.js — a zero-dependency SVG word/tag cloud.
@@ -212,7 +212,7 @@ Optional peers: `llms/peers.md`. `wa-*`/`sl-*` renames: `llms/migration.md`.
 - `lr-document-compare` · viewers/document-compare/document-compare.js — side-by-side or inline comparison of two document versions, composed entirely from two existing primitives rather than reimplementing eit...
 - `lr-geojson-view` · viewers/geojson-view/geojson-view.js — internal document-registry bridge rendering a fetched GeoJSON file through `<lr-map>`'s `dataLayers`.
 
-## Conversation & chat UI — `components/conversation/` (28)
+## Conversation & chat UI — `components/conversation/` (33)
 
 - `lr-markdown` · conversation/markdown/markdown.js — sanitized Markdown-to-HTML rendering (GFM tables, fenced code blocks, links, blockquotes) built on the optional peer dependencies `marked...
 - `lr-markdown-core` · conversation/markdown/markdown-core.js — a build-lean variant of `<lr-markdown>` for a consumer whose `languages` map already covers every language it will ever render.
@@ -242,8 +242,13 @@ Optional peers: `llms/peers.md`. `wa-*`/`sl-*` renames: `llms/migration.md`.
 - `lr-widget-renderer` · conversation/widget-renderer/widget-renderer.js — renders an agent-streamed declarative JSON widget tree through an allowlisted `type -> lyra tag` registry (see `registry.ts`/`resolve.ts`...
 - `lr-voice-picker` · conversation/voice-picker/voice-picker.js — a TTS voice selector over a host-supplied `catalog`, mirroring `lr-model-select`'s closed-dropdown/free-text-combobox dual mode, stale-va...
 - `lr-agent-workspace` · conversation/agent-workspace/agent-workspace.js — a responsive, controlled shell for an AI conversation and its supporting agent state.
+- `lr-message-parts` · conversation/message-parts/message-parts.js — renders ordered, interleavable provider-neutral AI message parts.
+- `lr-prompt-input` · conversation/prompt-input/prompt-input.js — a composed AI prompt surface combining the chat composer with attachments, model and voice selection, retrieval sources, mentions, slash...
+- `lr-prompt-queue` · conversation/prompt-queue/prompt-queue.js — a controlled queue of follow-up prompts that can be edited, reordered, removed, or sent immediately while another agent turn is active.
+- `lr-selection-toolbar` · conversation/selection-toolbar/selection-toolbar.js — a nonmodal action toolbar positioned above selected text.
+- `lr-realtime-session` · conversation/realtime-session/realtime-session.js — a provider-neutral voice-session shell composing connection status, live activity, transcript, native capture, mute, interruption, and co...
 
-## Agent tooling, tool calls & evaluation — `components/agent-tools/` (31)
+## Agent tooling, tool calls & evaluation — `components/agent-tools/` (35)
 
 - `lr-tool-call-chip` · agent-tools/tool-call-chip/tool-call-chip.js — a compact inline pill representing one tool/ function call an agent made mid-conversation, e.g.
 - `lr-tool-result-view` · agent-tools/tool-result-view/tool-result-view.js — renders a tool call's result via whichever custom renderer a host app has registered for it (see `registerToolRenderer()` in `registry.ts...
@@ -276,8 +281,12 @@ Optional peers: `llms/peers.md`. `wa-*`/`sl-*` renames: `llms/migration.md`.
 - `lr-tool-timeline` · agent-tools/tool-timeline/tool-timeline.js — a chronological list of an agent run's tool/function calls, each rendered through `<lr-tool-call-chip>` (name/status/duration) and `<lr-t...
 - `lr-agent-eval-dashboard` · agent-tools/agent-eval-dashboard/agent-eval-dashboard.js — a controlled evaluation overview with metric cards, a trend chart, and run-status history.
 - `lr-approval-queue` · agent-tools/approval-queue/approval-queue.js — a controlled queue of tool calls that need human approval, with a keyboard-accessible request list and a single reused `<lr-tool-approval...
+- `lr-mcp-app` · agent-tools/mcp-app/mcp-app.js — hosts an MCP App-style executable UI resource in a uniquely-origin sandbox.
+- `lr-prompt-studio` · agent-tools/prompt-studio/prompt-studio.js — a provider-neutral prompt-development workbench for ordered role messages, `{{variable}}` substitution, version selection, preview, save,...
+- `lr-schema-viewer` · agent-tools/schema-viewer/schema-viewer.js — a recursive, selectable JSON Schema inspector with required-state, constraints, composition branches, `$ref` display, validation issues,...
+- `lr-subagent-panel` · agent-tools/subagent-panel/subagent-panel.js — a controlled hierarchy of nested agent runs with lifecycle status, task/model context, progress, selection, cancellation, and retry intents.
 
-## Retrieval, knowledge graph & grounding — `components/retrieval/` (27)
+## Retrieval, knowledge graph & grounding — `components/retrieval/` (30)
 
 - `lr-graph` · retrieval/graph/graph.js — a force-directed node-link diagram with pan/zoom/drag.
 - `lr-node-palette` · retrieval/node-palette/node-palette.js — the searchable, categorized node library for workflow editors: drag an item onto a canvas, or place it by keyboard.
@@ -306,3 +315,6 @@ Optional peers: `llms/peers.md`. `wa-*`/`sl-*` renames: `llms/migration.md`.
 - `lr-rag-answer` · retrieval/rag-answer/rag-answer.js — a controlled grounded-answer surface combining sanitized Markdown, citation badges, a grounding assessment, and source previews.
 - `lr-embedding-explorer` · retrieval/embedding-explorer/embedding-explorer.js — a dependency-free, accessible 2D embedding projection viewer.
 - `lr-knowledge-base-admin` · retrieval/knowledge-base-admin/knowledge-base-admin.js — a responsive operations shell composing the existing controlled source inventory and ingestion queue into one tabbed knowledge-base view.
+- `lr-claim-evidence` · retrieval/claim-evidence/claim-evidence.js — a controlled claim-by-claim grounding audit.
+- `lr-retrieval-compare` · retrieval/retrieval-compare/retrieval-compare.js — a side-by-side retrieval/reranking workbench that makes rank, overlap, and dense/sparse/rerank/final score changes inspectable.
+- `lr-rag-eval-dashboard` · retrieval/rag-eval-dashboard/rag-eval-dashboard.js — a controlled RAG quality overview with current metric cards, per-metric trends, evaluation slices, and run history.

package/llms/peers.md

@@ -12,31 +12,38 @@ If the peer is genuinely absent, the component falls back to an empty/degraded r
 `<lr-phone-input>` is the exception: it takes an explicit consumer-built adapter
 (`loadLibphonenumberAdapter()`) instead of importing `libphonenumber-js` itself.
 
+**SheetJS (`xlsx`).** The supported `>=0.20.3 <0.21.0` releases are distributed by SheetJS
+from its CDN, not the public npm registry (whose newest release is 0.18.5). Install the peer
+with `pnpm add https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz` (or the equivalent npm
+command), matching the range below. The npm-published 0.18.5 release has unresolved advisories;
+do not run `npm audit fix --force` to address them when it proposes downgrading lyra-ui. That
+changes the component library version without installing a supported SheetJS release.
+
 | Peer | Range | Needed by |
 |---|---|---|
 | `@aceshooting/lyra-flags` | `workspace:^2.0.0` | `lr-flag`, `lr-phone-input` |
 | `@aiden0z/pptx-renderer` | `^1.2.4` | `lr-pptx-viewer` |
-| `@sgratzl/chartjs-chart-boxplot` | `^4.4.0` | `lr-box-plot` |
-| `chart.js` | `^4.5.0` | `lr-bar-chart`, `lr-box-plot`, `lr-bubble-chart`, `lr-chart`, `lr-doughnut-chart`, `lr-histogram`, `lr-line-chart`, `lr-pie-chart`, `lr-polar-area-chart`, `lr-radar-chart`, `lr-scatter-chart` |
+| `@sgratzl/chartjs-chart-boxplot` | `^4.4.5` | `lr-box-plot` |
+| `chart.js` | `^4.5.1` | `lr-bar-chart`, `lr-box-plot`, `lr-bubble-chart`, `lr-chart`, `lr-doughnut-chart`, `lr-histogram`, `lr-line-chart`, `lr-pie-chart`, `lr-polar-area-chart`, `lr-radar-chart`, `lr-scatter-chart` |
 | `chartjs-plugin-datalabels` | `^2.2.0` | `lr-bar-chart`, `lr-box-plot`, `lr-bubble-chart`, `lr-chart`, `lr-doughnut-chart`, `lr-histogram`, `lr-line-chart`, `lr-pie-chart`, `lr-polar-area-chart`, `lr-radar-chart`, `lr-scatter-chart` |
 | `chartjs-plugin-zoom` | `^2.2.0` | `lr-bar-chart`, `lr-box-plot`, `lr-bubble-chart`, `lr-chart`, `lr-doughnut-chart`, `lr-histogram`, `lr-line-chart`, `lr-pie-chart`, `lr-polar-area-chart`, `lr-radar-chart`, `lr-scatter-chart` |
 | `d3-drag` | `^3.0.0` | `lr-graph`, `lr-knowledge-graph-explorer` |
 | `d3-force` | `^3.0.0` | `lr-graph`, `lr-knowledge-graph-explorer` |
 | `d3-selection` | `^3.0.0` | `lr-graph`, `lr-knowledge-graph-explorer` |
 | `d3-zoom` | `^3.0.0` | `lr-graph`, `lr-knowledge-graph-explorer` |
-| `dompurify` | `^3.4.12` | `lr-docx-viewer`, `lr-email-viewer`, `lr-html-viewer`, `lr-include`, `lr-markdown`, `lr-markdown-core`, `lr-notebook-viewer`, `lr-svg-viewer` |
+| `dompurify` | `^3.4.12` | `lr-docx-viewer`, `lr-email-viewer`, `lr-html-viewer`, `lr-include`, `lr-markdown`, `lr-markdown-core`, `lr-message-parts`, `lr-notebook-viewer`, `lr-svg-viewer` |
 | `emoji-picker-element-data` | `^1.8.0` | `lr-emoji-picker` |
 | `epubjs` | `^0.3.93` | `lr-ebook-viewer` |
 | `ical.js` | `^2.2.1` | `lr-calendar-viewer` |
 | `jszip` | `^3.10.1` | `lr-archive-viewer` |
-| `katex` | `^0.17.0` | `lr-markdown`, `lr-markdown-core` |
+| `katex` | `^0.18.1` | `lr-markdown`, `lr-markdown-core`, `lr-message-parts` |
 | `libphonenumber-js` | `>=1.11.0 <2` | `lr-phone-input` |
 | `mammoth` | `^1.12.0` | `lr-docx-viewer` |
-| `maplibre-gl` | `^5.24.0` | `lr-geojson-view`, `lr-map` |
-| `marked` | `^18.0.6` | `lr-markdown`, `lr-markdown-core` |
-| `papaparse` | `^5.5.3` | `lr-csv-viewer`, `lr-dataset-viewer` |
+| `maplibre-gl` | `^6.0.0` | `lr-geojson-view`, `lr-map` |
+| `marked` | `^18.0.7` | `lr-markdown`, `lr-markdown-core`, `lr-message-parts` |
+| `papaparse` | `^5.5.4` | `lr-csv-viewer`, `lr-dataset-viewer` |
 | `pdfjs-dist` | `^6.1.200` | `lr-pdf-viewer` |
 | `postal-mime` | `^2.7.5` | `lr-email-viewer` |
 | `qrcode` | `^1.5.4` | `lr-qr-code` |
-| `shiki` | `^4.3.1` | `lr-code-block`, `lr-code-block-core`, `lr-diff-view`, `lr-document-compare`, `lr-markdown`, `lr-markdown-core` |
+| `shiki` | `^4.3.1` | `lr-code-block`, `lr-code-block-core`, `lr-diff-view`, `lr-document-compare`, `lr-markdown`, `lr-markdown-core`, `lr-message-parts` |
 | `xlsx` | `>=0.20.3 <0.21.0` | `lr-spreadsheet-viewer` |

package/llms/shared.md

@@ -8,7 +8,7 @@ import '@aceshooting/lyra-ui/components/forms/combobox/combobox.js'; // register
 import '@aceshooting/lyra-ui/components/data/table/table.js';        // registers <lr-table>
 ```
 
-`llms/index.md` lists the exact path for all 251 tags. A wrong or missing family segment is a hard
+`llms/index.md` lists the exact path for every tag. A wrong or missing family segment is a hard
 module-resolution failure, not a silent no-op — `exports` maps `./components/*` straight onto
 `./dist/components/*`.
 
@@ -21,8 +21,22 @@ module-resolution failure, not a silent no-op — `exports` maps `./components/*
   `lr-bar-chart`, `lr-pie-chart`, `lr-doughnut-chart`, `lr-radar-chart`, `lr-polar-area-chart`,
   `lr-bubble-chart`, `lr-scatter-chart`), `lr-box-plot`, `lr-histogram`, `lr-map`, `lr-graph`,
   `lr-knowledge-graph-explorer`, and `lr-geojson-view`. Those always need their own subpath import.
-  The barrel also re-exports every class and type (every `Lyra*EventMap` type included), so it is the
-  one import that defeats tree-shaking — prefer per-component entries in application code.
+  The barrel also re-exports a broad compatibility surface of commonly used classes, helpers, and
+  types, but it is not an exhaustive promise that every component-owned type or future export is
+  present. It is the one import that defeats tree-shaking — prefer the owning component entry in
+  application code, both for the smallest bundle and the complete contract of that component.
+- **Document anchor/highlight types.** The granular document-viewer entry owns and exports
+  `LyraAnchor`, `LyraAnchorKind`, `LyraHighlight`, `LyraHighlightTone`,
+  `AnchorTargetCapabilities`, `HighlightActivateDetail`, `TextSelectDetail`, and
+  `AnchorResultDetail`:
+  ```ts
+  import type {
+    LyraAnchor,
+    LyraHighlight,
+    AnchorTargetCapabilities,
+  } from '@aceshooting/lyra-ui/components/viewers/document-viewer/document-viewer.js';
+  ```
+  Use that entry instead of depending on incidental root-barrel coverage.
 - **`lr-flag`** registers from the barrel, but resolving a flag by `country`/`language` (rather than
   a pre-resolved `src`) additionally needs
   `import '@aceshooting/lyra-ui/components/media/flag/flag-peer.js';` once.
@@ -260,8 +274,12 @@ setLyraTheme({ mode: 'auto', accent: null });    // clears the override and the
 
 **No-flash bootstrap.** `lyraThemeBootstrap` is a self-contained IIFE **string** (not a function),
 meant to be inlined into a `<script>` in `<head>` **before any stylesheet**, so the persisted theme
-is on the root element before first paint. It is a string precisely so this can happen in an
-unbundled `<script>` context without shipping or parsing the module:
+is on the root element before first paint. It reads `localStorage['lyra-theme']`.
+`createLyraThemeBootstrap({ storageKey })` returns the same kind of string for an application-owned
+key, so an existing persistence layer can reuse the pre-paint half independently of
+`setLyraTheme()`/`getLyraTheme()`. Calling the factory with no options returns the same string as
+`lyraThemeBootstrap`. The result is a string precisely so this can happen in an unbundled
+`<script>` context without shipping or parsing the module:
 
 ```html
 <head>
@@ -270,9 +288,9 @@ unbundled `<script>` context without shipping or parsing the module:
 </head>
 ```
 
-It reads the same storage key, applies the same two attributes and `--lr-theme-accent`, and
-swallows any error — malformed storage or a blocked `localStorage` leaves the document untouched
-rather than throwing before your app loads.
+Both variants expect a stored `{ mode, accent }` record, apply the same two attributes and
+`--lr-theme-accent`, and swallow any error — malformed storage or a blocked `localStorage` leaves
+the document untouched rather than throwing before your app loads.
 
 **This runtime does no color math.** It stores and applies whatever accent string you give it; it
 does not validate the value, compute a palette from it, or check contrast against any surface.
@@ -339,13 +357,29 @@ instead of hand-rolling state shapes — they bind field-for-field onto the comp
 adapter layer:
 
 ```ts
-import type { AgentRun, ChatMessage, ToolInvocation, RetrievalChunk } from '@aceshooting/lyra-ui/ai';
+import {
+  createAgentStreamState,
+  reduceAgentStream,
+  adaptAiSdkStream,
+  adaptAgUiEvents,
+  adaptA2UiSurface,
+  type AgentRun,
+  type ChatMessage,
+  type MessagePart,
+  type RetrievalChunk,
+} from '@aceshooting/lyra-ui/ai';
 ```
 
 - **Run/step state** — `AgentStatusKind`, `AgentStatus`, `AgentStep`, `AgentRun`
-- **Conversation** — `ChatMessage`, `ToolInvocation`
+- **Conversation** — `ChatMessage`, ordered `MessagePart` variants, `ToolInvocation`
 - **Documents & grounding** — `DocumentRef`, `Citation`, `RetrievalQuery`, `RetrievalChunk`,
-  `GroundingAssessment`
+  `RetrievalScoreBreakdown`, `GroundedClaim`, `GroundingAssessment`, `DocumentLocator`
+- **Streaming runtime** — `AgentStreamEvent`, `AgentStreamState`, `createAgentStreamState()`,
+  `reduceAgentStream()`, `reduceAgentStreamEvents()`; event ids make replay/duplicate delivery
+  deterministic, and JSON Patch application rejects prototype-mutating paths
+- **Protocol adapters** — `adaptAiSdkStream()`, `adaptAgUiEvents()`, and `adaptA2UiSurface()` map
+  structural provider events/documents onto the neutral runtime without pulling vendor SDKs into
+  the package
 - **Event payloads** — `RunLifecycleEventDetail`, `RetrievalProgressEventDetail`,
   `CitationSelectEventDetail`, `ToolApprovalEventDetail`, `CancelEventDetail`, `RetryEventDetail`,
   `ExportEventDetail`
@@ -356,15 +390,35 @@ feeds on `lr-chat-message`, `lr-tool-call-chip`, `lr-tool-result-view`, `lr-sour
 convention. The types are structural and provider-agnostic: map any vendor's payload onto them once,
 at the edge.
 
+### Task-first AI composition guide
+
+- **Render one model response:** `lr-message-parts`; use `lr-chat-message` only when the message
+  shell (avatar, author, actions) is also needed.
+- **Build the main prompt affordance:** `lr-prompt-input`; it already composes attachments,
+  model/voice/source controls, mentions/commands, and `lr-prompt-queue`.
+- **Run an agent workspace:** `lr-agent-workspace` + `reduceAgentStream()`; add
+  `lr-subagent-panel` for nested runs and `lr-mcp-app` only for executable MCP App resources.
+- **Show grounded output:** `lr-rag-answer`; pass claim records for `lr-claim-evidence`, use
+  `lr-retrieval-compare` for retrieval tuning and `lr-rag-eval-dashboard` for run metrics.
+- **Develop prompts/tools:** `lr-prompt-studio` and `lr-schema-viewer`.
+- **Build voice sessions:** `lr-realtime-session`; it composes the existing audio visualizer,
+  push-to-talk control, and transcript feed while leaving transport ownership with the host.
+
+Family registration entry points are additive: importing
+`@aceshooting/lyra-ui/components/conversation`, `/agent-tools`, or `/retrieval` registers and
+exports that complete family. Granular component entry points remain the smallest bundles and are
+preferred in production.
+
 ## Optional peer dependencies
 
-All 26 peers are optional and lazily loaded; nothing is imported eagerly. `llms/peers.md` is the
-generated component → peer table. The shared contract: a component resolves its peer through a
-dynamic `import()` on first use, rendering an `<lr-skeleton>` placeholder with `aria-busy="true"` on
-the host meanwhile; if the peer is genuinely absent it falls back to an empty/degraded render plus a
-single deduped `console.warn` — it never throws and never blocks paint. `lr-phone-input` is the
-exception: it takes a consumer-built adapter (`loadLibphonenumberAdapter()`) rather than importing
-`libphonenumber-js` itself.
+All 26 peers are optional and their implementations are loaded on demand; nothing is imported
+eagerly. `llms/peers.md` is the generated component → peer table. Loading and failure UI is
+component-specific: viewer sections document their localized loading/error/notice states, while
+`lr-include` preserves its light-DOM fallback/live region and emits `lr-include-error` when its
+sanitizer is unavailable. Some components additionally issue a deduped warning. Consult the owning
+component section instead of assuming every peer user renders an `<lr-skeleton>` or the same
+degraded state. `lr-phone-input` is the exception to dynamic peer import: it takes a consumer-built
+adapter (`loadLibphonenumberAdapter()`) rather than importing `libphonenumber-js` itself.
 
 ## Framework integration