@aceshooting/lyra-ui 6.1.0 → 7.0.0

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.
@@ -190,6 +204,98 @@ dark palette — that fallback applies only where no real `--lr-theme-*` value i
 The token layer also sets `:host([hidden]) { display: none !important; }` and an inherited
 `box-sizing: border-box` reset.
 
+### Theme mode/accent runtime (`@aceshooting/lyra-ui/theme.js`)
+
+Flipping the mode class/attribute above is something every app ends up hand-rolling — persist a
+choice, apply it on load, avoid the flash of wrong theme before the app boots. `theme.js` is that
+runtime, published as its own subpath: **zero dependencies, no Lit, no component imports, and no
+side effects on import**, so an app can persist and apply a theme without pulling the component
+graph into its first-paint bundle.
+
+```ts
+import { setLyraTheme, getLyraTheme } from '@aceshooting/lyra-ui/theme.js';
+
+setLyraTheme({ mode: 'dark' });                  // unspecified fields keep their current value
+setLyraTheme({ accent: '#7c3aed' });             // mode stays 'dark'
+getLyraTheme();                                  // → { mode: 'dark', accent: '#7c3aed' }
+setLyraTheme({ mode: 'auto', accent: null });    // clears the override and the accent
+```
+
+- **`setLyraTheme({ mode?, accent? })`** persists to `localStorage['lyra-theme']`, applies to
+  `document.documentElement`, and dispatches `lr-theme-change` on `window` with
+  `detail: { mode, accent }`. Fields you omit keep their current value; pass `null` to clear the
+  accent. It **never throws** — when `localStorage` is unavailable (private browsing, quota, a
+  sandboxed iframe) it degrades to apply-without-persist, and the "fields you omit keep their
+  current value" rule still holds across calls in that state: the merge falls back to the last
+  theme applied in this session rather than to the default.
+- **`getLyraTheme()`** returns `{ mode, accent }`, defaulting to `{ mode: 'auto', accent: null }`
+  when nothing is stored or the stored value is malformed. Storage is re-read on every call — no
+  in-memory cache — so a value written by another tab or a previous session is picked up cold.
+  Where storage is unreadable or unwritable it reports the theme last applied, so the return value
+  always describes what the document is actually showing and a toggle UI bound to it stays in sync.
+- **`mode`** is `'light' | 'dark' | 'auto'`. `'light'`/`'dark'` set **both `data-lr-theme`** (the
+  attribute `theme.css` actually keys its palette blocks on) **and `data-theme`** (the generic
+  attribute canvas-rendered components watch, so `lr-chart`/`lr-heatmap`/`lr-qr-code` repaint on
+  the switch rather than keeping stale colors — see `llms/components/lr-chart.md`). `'auto'`
+  removes both, which means **no override — not "follow the OS"**:
+  - **With `theme.css` imported** (the setup this section is nested under), its `:root` block sets
+    the full light palette unconditionally and that file ships no `prefers-color-scheme` block, so
+    `'auto'` renders **light** whatever the OS is set to.
+  - **Without `theme.css`**, no real `--lr-theme-*` value is set, so the token layer's
+    `prefers-color-scheme: dark` fallback described above does apply and bare components follow
+    the OS.
+
+  To follow the OS *alongside* `theme.css`, resolve the preference yourself and pass a concrete
+  mode — `setLyraTheme` deliberately does no `matchMedia` work of its own:
+  ```ts
+  const os = matchMedia('(prefers-color-scheme: dark)');
+  const sync = () => setLyraTheme({ mode: os.matches ? 'dark' : 'light' });
+  sync();
+  os.addEventListener('change', sync);
+  ```
+- **`accent`** is written to `--lr-theme-accent` as an inline custom property on the root element.
+  This is a **hook for your CSS, not a token the library reads** — no lyra-ui component consumes
+  `--lr-theme-accent`. Point the real inputs at it to make it retint anything, **writing one rule
+  per mode**:
+  ```css
+  :root { --lr-theme-color-brand-fill-loud: var(--lr-theme-accent, #0969da); }
+  .lr-dark,
+  [data-lr-theme='dark'] { --lr-theme-color-brand-fill-loud: var(--lr-theme-accent, #4ea0f0); }
+  ```
+  **Each arm's fallback must carry that mode's own value.** A single `:root` rule flattens both
+  modes to one color whenever the accent is unset (`accent: null`, the default): `:root` and
+  `[data-lr-theme='dark']` have equal specificity and both match `<html>` — the element
+  `setLyraTheme` writes `data-lr-theme` onto — so a consumer stylesheet loaded after `theme.css`
+  wins the tie on source order and pins the light-mode blue in dark mode. Copy each fallback from
+  the matching palette block in `theme.css` (`#0969da` light / `#4ea0f0` dark here).
+
+  Because that is a `--lr-theme-*` input, it reaches every nested shadow root — see "Where an
+  override actually reaches" above for why setting a `--lr-*` token instead would not.
+
+**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 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>
+  <script>/* server-inlines lyraThemeBootstrap here */</script>
+  <link rel="stylesheet" href="/theme.css" />
+</head>
+```
+
+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.
+Verifying that an accent meets WCAG contrast against the light *and* dark palettes is yours.
+
 ## Localization: `locale`, `strings`, and the locale runtime
 
 Every built-in string — button labels, accessible names, descriptions, validation messages, status
@@ -251,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`
@@ -268,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