@aceshooting/lyra-ui 6.1.0 → 7.0.0

package/dist/theme/theme.js

@@ -0,0 +1,143 @@
+/**
+ * Zero-dependency theme mode/accent runtime, published as the `@aceshooting/lyra-ui/theme.js`
+ * subpath. Nothing here imports Lit, any component, or any other module in this package: the
+ * whole point of the subpath is that an application can persist and apply a theme without
+ * pulling the component graph into its first-paint bundle. Keep it dependency-free.
+ *
+ * This module is side-effect-free -- importing it never touches the document or storage -- and
+ * therefore carries no `package.json#sideEffects` entry, so bundlers may drop it when unused.
+ */
+const STORAGE_KEY = 'lyra-theme';
+const DEFAULT_THEME = { mode: 'auto', accent: null };
+/**
+ * The last theme this module applied. `localStorage` is the source of truth whenever it is
+ * readable *and* writable; this is the fallback for the contexts where it is not (sandboxed
+ * iframe, blocked third-party storage, private browsing, quota exhaustion). Without it every
+ * `setLyraTheme` call would merge over `DEFAULT_THEME` and silently reset fields an earlier call
+ * set -- breaking the documented "degrades to apply-without-persist" guarantee across two calls --
+ * and `getLyraTheme()` would report a state the document does not actually have, so a toggle UI
+ * bound to it would render the wrong position.
+ */
+let lastApplied = DEFAULT_THEME;
+/**
+ * True once a persist attempt has thrown and has not since succeeded. Storage may still be
+ * *readable* in that state (quota exhaustion is the common case), but it no longer holds what we
+ * applied, so a read would return a stale value; `lastApplied` is the truer answer.
+ */
+let persistenceFailed = false;
+/**
+ * `theme.css` keys its light/dark blocks off `data-lr-theme` (and the equivalent `.lr-light`/
+ * `.lr-dark` classes). `data-theme` is the generic attribute apps and `ThemeWatcher`
+ * (`src/internal/theme-watcher.ts`, which canvas-rendered components use to know when to
+ * repaint) watch for. Both are written so a mode switch reaches the shipped stylesheet *and*
+ * triggers a canvas repaint; writing only one leaves half the library on the old theme.
+ */
+const MODE_ATTRIBUTES = ['data-lr-theme', 'data-theme'];
+function readStoredTheme() {
+    // Storage cannot be trusted to hold what we applied -- honour the session's own state instead.
+    if (persistenceFailed)
+        return lastApplied;
+    let raw;
+    try {
+        raw = localStorage.getItem(STORAGE_KEY);
+    }
+    catch {
+        // Storage is unreachable (sandboxed iframe, blocked third-party storage, private browsing).
+        // What this module last applied is a truer answer than the default.
+        return lastApplied;
+    }
+    // Reachable storage with nothing in it is a genuine "unset" -- distinct from the cases above,
+    // and the one case where the default really is correct.
+    if (!raw)
+        return DEFAULT_THEME;
+    try {
+        const parsed = JSON.parse(raw);
+        return {
+            mode: parsed.mode === 'light' || parsed.mode === 'dark' || parsed.mode === 'auto'
+                ? parsed.mode
+                : 'auto',
+            accent: typeof parsed.accent === 'string' && parsed.accent ? parsed.accent : null,
+        };
+    }
+    catch {
+        // Readable storage holding garbage (another tool wrote the key, a truncated write): also a
+        // genuine "nothing valid stored", so the default applies rather than `lastApplied`.
+        return DEFAULT_THEME;
+    }
+}
+function applyTheme(theme) {
+    lastApplied = theme;
+    const root = document.documentElement;
+    for (const attribute of MODE_ATTRIBUTES) {
+        if (theme.mode === 'auto')
+            root.removeAttribute(attribute);
+        else
+            root.setAttribute(attribute, theme.mode);
+    }
+    if (theme.accent)
+        root.style.setProperty('--lr-theme-accent', theme.accent);
+    else
+        root.style.removeProperty('--lr-theme-accent');
+}
+/**
+ * Sets the persisted theme mode/accent, applies it to `document.documentElement` (via
+ * `data-lr-theme`/`data-theme` and the `--lr-theme-accent` custom property), and dispatches
+ * `lr-theme-change` on `window` with `detail: { mode, accent }`. Unspecified fields keep their
+ * current value. Never throws -- a `localStorage` failure (private browsing, quota, sandboxed
+ * iframe) degrades to apply-without-persist, and unspecified fields still keep their value across
+ * calls in that state, because the merge falls back to the last applied theme rather than to the
+ * default. This module intentionally has zero dependencies and
+ * does not compute or validate color contrast -- see `llms/shared.md`'s "Theming and design
+ * tokens" section for the `--lr-theme-*` convention this integrates with.
+ */
+export function setLyraTheme(theme) {
+    const current = readStoredTheme();
+    const next = {
+        mode: theme.mode ?? current.mode,
+        accent: theme.accent === undefined ? current.accent : (theme.accent ?? null),
+    };
+    try {
+        localStorage.setItem(STORAGE_KEY, JSON.stringify(next));
+        persistenceFailed = false;
+    }
+    catch {
+        // Persistence is best-effort; the theme still applies for this session. Latching the failure
+        // makes subsequent calls merge over what we actually applied (`lastApplied`) instead of over
+        // a stale read or the default, so nothing silently resets.
+        persistenceFailed = true;
+    }
+    applyTheme(next);
+    window.dispatchEvent(new CustomEvent('lr-theme-change', { detail: next }));
+}
+/**
+ * Reads the current theme mode/accent, defaulting to `{ mode: 'auto', accent: null }` when
+ * nothing has been set or the stored value is malformed. Storage is re-read on every call --
+ * there is no in-memory cache -- so a value written by another tab or a previous session is
+ * picked up cold.
+ *
+ * When `localStorage` is unreadable or unwritable this reports the theme this module last
+ * applied, not the default: the returned value always describes what the document is actually
+ * showing, so a toggle UI bound to it stays in sync even where nothing can be persisted.
+ */
+export function getLyraTheme() {
+    return readStoredTheme();
+}
+/**
+ * Creates a self-contained IIFE body, safe to inline into a `<script>` tag placed before any
+ * stylesheet in `<head>`, that applies a persisted `{ mode, accent }` theme before first paint.
+ * Pass an application-owned `storageKey` to reuse the no-flash bootstrap independently of this
+ * module's `setLyraTheme()`/`getLyraTheme()` persistence key.
+ *
+ * The returned value is deliberately a plain string (not a function) so it can be inlined without
+ * shipping or parsing this whole module in an unbundled `<script>` context.
+ */
+export function createLyraThemeBootstrap(options = {}) {
+    const storageKey = options.storageKey ?? STORAGE_KEY;
+    return `(function(){try{var raw=localStorage.getItem(${JSON.stringify(storageKey)});if(!raw)return;var t=JSON.parse(raw);if(t.mode==='light'||t.mode==='dark'){${MODE_ATTRIBUTES.map((attribute) => `document.documentElement.setAttribute(${JSON.stringify(attribute)},t.mode);`).join('')}}if(typeof t.accent==='string'&&t.accent){document.documentElement.style.setProperty('--lr-theme-accent',t.accent);}}catch(e){}})();`;
+}
+/**
+ * The default-key no-flash bootstrap. Equivalent to `createLyraThemeBootstrap()` and retained for
+ * consumers that store their theme under `localStorage['lyra-theme']`.
+ */
+export const lyraThemeBootstrap = createLyraThemeBootstrap();
+//# sourceMappingURL=theme.js.map

package/dist/theme/theme.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme.js","sourceRoot":"","sources":["../../src/theme/theme.ts"],"names":[],"mappings":"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"}

package/llms/components/lr-accordion-item.md

@@ -6,6 +6,7 @@
 - **Class** `LyraAccordionItem`, also available unregistered from `@aceshooting/lyra-ui/components/layout/details/accordion-item.class.js`
 - **Family** `components/layout/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 3 parts, 0 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Documented with** `lr-details`, `lr-accordion` (same section below)
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 

package/llms/components/lr-accordion.md

@@ -6,6 +6,7 @@
 - **Class** `LyraAccordion`, also available unregistered from `@aceshooting/lyra-ui/components/layout/details/accordion.class.js`
 - **Family** `components/layout/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 1 part, 0 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Documented with** `lr-details`, `lr-accordion-item` (same section below)
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 

package/llms/components/lr-activity-feed.md

@@ -6,6 +6,7 @@
 - **Class** `LyraActivityFeed`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/activity-feed/activity-feed.class.js`
 - **Family** `components/agent-tools/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 17 parts, 1 custom property — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---

package/llms/components/lr-agent-eval-dashboard.md

@@ -0,0 +1,36 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/agent-tools.md — do not edit this file. -->
+
+# `lr-agent-eval-dashboard`
+
+- **Import** `import '@aceshooting/lyra-ui/components/agent-tools/agent-eval-dashboard/agent-eval-dashboard.js';` (registers the tag; side-effect import)
+- **Class** `LyraAgentEvalDashboard`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/agent-eval-dashboard/agent-eval-dashboard.class.js`
+- **Family** `components/agent-tools/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Themeable via** 12 parts, 2 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`
+
+---
+
+## `lr-agent-eval-dashboard`
+
+Controlled evaluation overview with metric cards, a dependency-free trend chart, and run-status
+history. It never launches or scores evaluations.
+
+**Properties:** `metrics: AgentEvaluationMetric[] = []` (attribute: false), where each metric is
+`{ id, label, value, format?: 'number' | 'percent' | 'milliseconds' | 'currency' }`; `currency:
+string = 'USD'` is the ISO 4217 code used by currency-formatted metrics (invalid codes safely fall
+back to USD). `runs:
+AgentEvaluationDashboardRun[] = []` (attribute: false), where each run is `{ id, label, status,
+metrics?: Record<string, number> }`; `metricId: string = ''`; `label: string = ''`; `showChart:
+boolean = true`; `chartHeight: string = '220px'`.
+
+**Events:** `lr-metric-change` (`{ metricId }`, emitted when a metric selector is activated) and
+`lr-run-select` (`{ runId }`).
+
+**CSS parts:** `base`, `heading`, `metrics`, `metric`, `chart`, `runs`, `runs-heading`, `run`,
+`run-label`, `run-meta`, `run-status`, `empty`.
+
+**Additional API surface:**
+
+- `--lr-agent-eval-dashboard-active-border` — Active metric border. Default: `var(--lr-color-brand)`.
+- `--lr-agent-eval-dashboard-active-background` — Active metric background. Default: `var(--lr-color-brand-quiet)`.

package/llms/components/lr-agent-run.md

@@ -6,6 +6,7 @@
 - **Class** `LyraAgentRun`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/agent-run/agent-run.class.js`
 - **Family** `components/agent-tools/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 25 parts, 6 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`
 
 ---
@@ -79,3 +80,9 @@ padding, and the gap between its header and body, while `compact`; both are igno
 is unset. Like the other density/state properties in this family they are inline `var()` fallbacks at
 their point of use rather than `:host` declarations, so either can be set on the element *or on any
 ancestor* — one rule on a run list retunes every compact run inside it.
+
+**Additional API surface:**
+
+- `--lr-agent-run-metric-danger-color` — Danger metric value. Default: `var(--lr-color-danger)`.
+- `--lr-agent-run-metric-success-color` — Success metric value. Default: `var(--lr-color-success)`.
+- `--lr-agent-run-metric-warning-color` — Warning metric value. Default: `var(--lr-color-warning)`.

package/llms/components/lr-agent-trace.md

@@ -6,6 +6,7 @@
 - **Class** `LyraAgentTrace`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/agent-trace/agent-trace.class.js`
 - **Family** `components/agent-tools/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 5 parts, 1 custom property — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---

package/llms/components/lr-agent-workspace.md

@@ -6,6 +6,7 @@
 - **Class** `LyraAgentWorkspace`, also available unregistered from `@aceshooting/lyra-ui/components/conversation/agent-workspace/agent-workspace.class.js`
 - **Family** `components/conversation/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 15 parts, 0 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`
 
 ---

package/llms/components/lr-animated-image.md

@@ -6,6 +6,7 @@
 - **Class** `LyraAnimatedImage`, also available unregistered from `@aceshooting/lyra-ui/components/media/animated-image/animated-image.class.js`
 - **Family** `components/media/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 5 parts, 3 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`
 
 ---
@@ -64,3 +65,7 @@ backgrounded circle around the button; only rendered once loaded and error-free)
 - both `image` and `canvas` stay mounted at all times (never `display: none`/removed) so the
   browser's native decode loop keeps running while visually covered; only opacity and `aria-hidden`
   swap.
+
+**Additional API surface:**
+
+- `click()` — Activate the play/pause control.

package/llms/components/lr-animation.md

@@ -6,6 +6,7 @@
 - **Class** `LyraAnimation`, also available unregistered from `@aceshooting/lyra-ui/components/media/animation/animation.class.js`
 - **Family** `components/media/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 0 parts, 4 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`
 
 ---

package/llms/components/lr-app-rail-item.md

@@ -6,6 +6,7 @@
 - **Class** `LyraAppRailItem`, also available unregistered from `@aceshooting/lyra-ui/components/layout/app-rail/app-rail-item.class.js`
 - **Family** `components/layout/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 4 parts, 2 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Documented with** `lr-app-rail` (same section below)
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
@@ -27,8 +28,13 @@ content is never duplicated.
 
 Opting in to `resizable` adds a continuously draggable width for the `'full'` state: a
 `[part="resizer"]` handle (pointer-drag and Left/Right-arrow keyboard stepping, RTL-aware) clamped to
-`[minRailWidthPx, maxRailWidthPx]`, with no built-in persistence — a consumer that wants the chosen
-width to survive a reload listens for `lr-rail-resize` and persists `railWidthPx` itself.
+`[minRailWidthPx, maxRailWidthPx]`. Set `storageKey` (attribute `storage-key`) to persist the fields
+selected by `persist` to `localStorage` under `lr-app-rail:${storageKey}` and restore them on the
+next mount (mirrors `lr-split`'s `storage-key`; effective `mode` is breakpoint-derived and never
+persisted). The backward-compatible allowlist is `open width`; use
+`persist="width preferred-mode"` for durable layout preference without restoring the transient
+mobile overlay. Without a `storageKey` there is no persistence — listen for `lr-rail-resize` and
+persist `widthPx` yourself.
 `preferredMode` separately lets a host manually prefer `'full'`/`'icon-only'` for the non-mobile
 breakpoint axis (e.g. a user's own collapse toggle) while `mobile-breakpoint` continues to be tracked
 automatically regardless — it's only consulted while `mode` isn't force-pinned via the `mode`
@@ -73,6 +79,14 @@ accessor itself, which still takes full priority.
 - `railWidthPx?: number` (attribute `rail-width-px`) — the rail's current width in px while
   `resizable`; settable/gettable directly. Unset defers to `--lr-app-rail-width`'s own resolved
   width.
+- `storageKey?: string` (attribute `storage-key`) — when set, persists the fields selected by
+  `persist` to `localStorage` under `lr-app-rail:${storageKey}` and restores them on the next
+  mount. Effective `mode` is breakpoint-derived and never persisted. Unset means no persistence.
+- `persist: string = 'open width'` — whitespace-separated field allowlist used with `storageKey`.
+  Valid `AppRailPersistField` tokens are `open`, `width` (`railWidthPx`), and `preferred-mode`
+  (`preferredMode`). The default preserves the existing open+width behavior. Use
+  `persist="width preferred-mode"` when overlay-open state is controlled or should stay
+  session-only.
 - `minRailWidthPx: number = 190` (attribute `min-rail-width-px`) — minimum `railWidthPx` a
   drag/keyboard resize can reach.
 - `maxRailWidthPx: number = 440` (attribute `max-rail-width-px`) — maximum `railWidthPx` a

package/llms/components/lr-app-rail.md

@@ -6,6 +6,7 @@
 - **Class** `LyraAppRail`, also available unregistered from `@aceshooting/lyra-ui/components/layout/app-rail/app-rail.class.js`
 - **Family** `components/layout/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 9 parts, 4 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Documented with** `lr-app-rail-item` (same section below)
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
@@ -27,8 +28,13 @@ content is never duplicated.
 
 Opting in to `resizable` adds a continuously draggable width for the `'full'` state: a
 `[part="resizer"]` handle (pointer-drag and Left/Right-arrow keyboard stepping, RTL-aware) clamped to
-`[minRailWidthPx, maxRailWidthPx]`, with no built-in persistence — a consumer that wants the chosen
-width to survive a reload listens for `lr-rail-resize` and persists `railWidthPx` itself.
+`[minRailWidthPx, maxRailWidthPx]`. Set `storageKey` (attribute `storage-key`) to persist the fields
+selected by `persist` to `localStorage` under `lr-app-rail:${storageKey}` and restore them on the
+next mount (mirrors `lr-split`'s `storage-key`; effective `mode` is breakpoint-derived and never
+persisted). The backward-compatible allowlist is `open width`; use
+`persist="width preferred-mode"` for durable layout preference without restoring the transient
+mobile overlay. Without a `storageKey` there is no persistence — listen for `lr-rail-resize` and
+persist `widthPx` yourself.
 `preferredMode` separately lets a host manually prefer `'full'`/`'icon-only'` for the non-mobile
 breakpoint axis (e.g. a user's own collapse toggle) while `mobile-breakpoint` continues to be tracked
 automatically regardless — it's only consulted while `mode` isn't force-pinned via the `mode`
@@ -73,6 +79,14 @@ accessor itself, which still takes full priority.
 - `railWidthPx?: number` (attribute `rail-width-px`) — the rail's current width in px while
   `resizable`; settable/gettable directly. Unset defers to `--lr-app-rail-width`'s own resolved
   width.
+- `storageKey?: string` (attribute `storage-key`) — when set, persists the fields selected by
+  `persist` to `localStorage` under `lr-app-rail:${storageKey}` and restores them on the next
+  mount. Effective `mode` is breakpoint-derived and never persisted. Unset means no persistence.
+- `persist: string = 'open width'` — whitespace-separated field allowlist used with `storageKey`.
+  Valid `AppRailPersistField` tokens are `open`, `width` (`railWidthPx`), and `preferred-mode`
+  (`preferredMode`). The default preserves the existing open+width behavior. Use
+  `persist="width preferred-mode"` when overlay-open state is controlled or should stay
+  session-only.
 - `minRailWidthPx: number = 190` (attribute `min-rail-width-px`) — minimum `railWidthPx` a
   drag/keyboard resize can reach.
 - `maxRailWidthPx: number = 440` (attribute `max-rail-width-px`) — maximum `railWidthPx` a

package/llms/components/lr-approval-queue.md

@@ -0,0 +1,31 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/agent-tools.md — do not edit this file. -->
+
+# `lr-approval-queue`
+
+- **Import** `import '@aceshooting/lyra-ui/components/agent-tools/approval-queue/approval-queue.js';` (registers the tag; side-effect import)
+- **Class** `LyraApprovalQueue`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/approval-queue/approval-queue.class.js`
+- **Family** `components/agent-tools/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Themeable via** 11 parts, 1 custom property — see this component's own `@csspart`/`@cssprop` list below
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-approval-queue`
+
+Keyboard-accessible queue of pending tool calls backed by one reusable `lr-tool-approval-dialog`.
+It never executes tools or persists decisions.
+
+**Properties:** `requests: ToolApprovalRequest[] = []` (attribute: false), where each request is
+`{ id, toolName, args, status?: 'pending' | 'approved' | 'denied' }`; `selectedId: string = ''`;
+`open: boolean = false`; `editable: boolean = true`; `label: string = ''`.
+
+**Events:** `lr-approval-select` (`{ invocationId }`), `lr-approval-decision` (`{ invocationId,
+approved, args? }`), and `lr-approval-close` (`{ invocationId, reason }`).
+
+**CSS parts:** `base`, `heading-row`, `heading`, `count`, `list`, `request`, `request-info`,
+`tool-name`, `request-id`, `status`, `empty`.
+
+**Additional API surface:**
+
+- `--lr-approval-queue-selected-border` — Selected request border. Default: `var(--lr-color-brand)`.

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

@@ -6,6 +6,7 @@
 - **Class** `LyraArchiveViewer`, also available unregistered from `@aceshooting/lyra-ui/components/viewers/archive-viewer/archive-viewer.class.js`
 - **Family** `components/viewers/` — see `llms/index.md` for its siblings
 - **Optional peers** `jszip` — see `llms/peers.md`
+- **Themeable via** 9 parts, 0 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`
 
 ---
@@ -18,12 +19,17 @@ read straight from JSZip's local file header (`uncompressedSize`) when available
 fully decompressing only the rare entry missing that header field. The list composes
 `<lr-virtual-list>` for large archives.
 
-**Properties:** `src` and `name` are strings — `name` (or a host-level `aria-label`) names the
-listing region as `role="region"`; with neither set, the region is unnamed.
+**Properties:** `src` and `name` are strings — a host-level `aria-label` takes precedence over
+`name` when naming the `role="region"` listing. The viewer also exposes the shared text-viewer
+contract: `highlights`, `activeHighlightId`, `anchor`, and `anchorKinds` (`['text-quote', 'fragment']`).
+
+**Methods:** `search(query)`, `searchNext()`, `searchPrevious()`, and `clearSearch()` provide
+case-insensitive text search over rendered entry names; `scrollToAnchor()` resolves text-quote and
+fragment anchors and emits `lr-anchor-result`.
 
 **Events:** `lr-render-error` with `detail.error` when fetching or parsing fails.
 
-**CSS parts:** `base`, `entry`, `entry-icon`, `entry-name`, `entry-name-dir`, `entry-size`,
+**CSS parts:** `base`, `body`, `entry`, `entry-icon`, `entry-name`, `entry-name-dir`, `entry-size`,
 `spinner`, and `error`. A directory row's name element carries both `entry-name` and
 `entry-name-dir` (a part list), so `::part(entry-name-dir)` selects only directory names while
 `::part(entry-name)` still selects every name. Entry rows are rendered into the embedded

package/llms/components/lr-artifact-panel.md

@@ -6,6 +6,7 @@
 - **Class** `LyraArtifactPanel`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/artifact-panel/artifact-panel.class.js`
 - **Family** `components/agent-tools/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 18 parts, 2 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`
 
 ---

package/llms/components/lr-attachment-chip.md

@@ -6,6 +6,7 @@
 - **Class** `LyraAttachmentChip`, also available unregistered from `@aceshooting/lyra-ui/components/media/attachment-chip/attachment-chip.class.js`
 - **Family** `components/media/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 12 parts, 7 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`
 
 ---

package/llms/components/lr-attachment-trigger.md

@@ -6,6 +6,7 @@
 - **Class** `LyraAttachmentTrigger`, also available unregistered from `@aceshooting/lyra-ui/components/media/attachment-trigger/attachment-trigger.class.js`
 - **Family** `components/media/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 5 parts, 0 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`
 
 ---
@@ -87,4 +88,8 @@ hidden via CSS by default, exposed as a part only so a consumer can override tha
   scope-limited by design to firing `lr-camera-request`/`lr-audio-request` and nothing else. The
   hidden input is only rendered when `capabilities` contains `files` or `image`.
 
+**Additional API surface:**
+
+- `click()` — Activates the internal attachment trigger.
+
 ---

package/llms/components/lr-audio-visualizer.md

@@ -6,6 +6,7 @@
 - **Class** `LyraAudioVisualizer`, also available unregistered from `@aceshooting/lyra-ui/components/conversation/audio-visualizer/audio-visualizer.class.js`
 - **Family** `components/conversation/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 2 parts, 3 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`
 
 ---

package/llms/components/lr-av-player.md

@@ -6,6 +6,7 @@
 - **Class** `LyraAvPlayer`, also available unregistered from `@aceshooting/lyra-ui/components/media/av-player/av-player.class.js`
 - **Family** `components/media/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 15 parts, 9 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`
 
 ---
@@ -20,8 +21,8 @@ distinct from `<lr-transcript-feed>` (live captions for an in-progress voice ses
 `anchorKinds: ['time-range']` only — no text selection is bound. The transcript virtualizes through
 `<lr-virtual-list>` the same way `lr-pdf-viewer` virtualizes pages.
 
-**Properties:** `src: string = ''`, `name: string = ''`, `kind?: 'audio' | 'video'` (attribute:
-false auto-detection override), `mimeType: string = ''` (attribute `mime-type`), `poster: string =
+**Properties:** `src: string = ''`, `name: string = ''`, `kind?: 'audio' | 'video'`
+(attribute-backed 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:

package/llms/components/lr-avatar-group.md

@@ -6,6 +6,7 @@
 - **Class** `LyraAvatarGroup`, also available unregistered from `@aceshooting/lyra-ui/components/media/avatar-group/avatar-group.class.js`
 - **Family** `components/media/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 2 parts, 7 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`
 
 ---

package/llms/components/lr-avatar.md

@@ -6,6 +6,7 @@
 - **Class** `LyraAvatar`, also available unregistered from `@aceshooting/lyra-ui/components/media/avatar/avatar.class.js`
 - **Family** `components/media/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 4 parts, 4 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`
 
 ---

package/llms/components/lr-badge.md

@@ -6,6 +6,7 @@
 - **Class** `LyraBadge`, also available unregistered from `@aceshooting/lyra-ui/components/overlays/badge/badge.class.js`
 - **Family** `components/overlays/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 1 part, 7 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Documented with** `lr-tag` (same section below)
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 

package/llms/components/lr-bar-chart.md

@@ -5,7 +5,8 @@
 - **Import** `import '@aceshooting/lyra-ui/components/charts/chart/bar-chart.js';` (registers the tag; side-effect import)
 - **Class** `LyraBarChart`, also available unregistered from `@aceshooting/lyra-ui/components/charts/chart/bar-chart.class.js`
 - **Family** `components/charts/` — see `llms/index.md` for its siblings
-- **Optional peers** `chart.js`, `chartjs-plugin-zoom` — see `llms/peers.md`
+- **Optional peers** `chart.js`, `chartjs-plugin-datalabels`, `chartjs-plugin-zoom` — see `llms/peers.md`
+- **Themeable via** 7 parts, 6 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Documented with** `lr-line-chart`, `lr-pie-chart`, `lr-doughnut-chart`, `lr-radar-chart`, `lr-polar-area-chart`, `lr-bubble-chart`, `lr-scatter-chart` (same section below)
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
@@ -26,7 +27,8 @@ of every entry in these lists.**
 
 **Properties:** `labels`, `datasets`, `legend`, `legendPosition` (attribute `legend-position`),
 `valueFormatter`, `area`, `zoom`, `height`, `xLabel` (`x-label`), `yLabel` (`y-label`), `y2Label`
-(`y2-label`), `beginAtZero` (`begin-at-zero`), `horizontal`, `stacked`, `config`, `accessibleLabel`
+(`y2-label`), `beginAtZero` (`begin-at-zero`), `horizontal`, `stacked`, `dataLabels`
+(`data-labels`), `stackTotals` (`stack-totals`), `config`, `accessibleLabel`
 (`accessible-label`), `accessibleDescription` (`accessible-description`), `showDataTable`
 (`show-data-table`), `chartArea` (readonly). `type` is the only member that differs: read-only,
 locked to this tag's value.
@@ -47,7 +49,7 @@ dependency fails to load — see `llms/components/lr-chart.md`).
 `--lr-chart-tooltip-text`.
 
 **Optional peer deps:** same as `lr-chart` — `chart.js`, plus `chartjs-plugin-zoom` only once
-`zoom` is set.
+`zoom` is set, and `chartjs-plugin-datalabels` only once `data-labels`/`stack-totals` is set.
 
 ```html
 <lr-bar-chart legend></lr-bar-chart>

package/llms/components/lr-box-plot.md

@@ -5,7 +5,8 @@
 - **Import** `import '@aceshooting/lyra-ui/components/charts/chart/box-plot.js';` (registers the tag; side-effect import)
 - **Class** `LyraBoxPlot`, also available unregistered from `@aceshooting/lyra-ui/components/charts/chart/box-plot.class.js`
 - **Family** `components/charts/` — see `llms/index.md` for its siblings
-- **Optional peers** `@sgratzl/chartjs-chart-boxplot`, `chart.js`, `chartjs-plugin-zoom` — see `llms/peers.md`
+- **Optional peers** `@sgratzl/chartjs-chart-boxplot`, `chart.js`, `chartjs-plugin-datalabels`, `chartjs-plugin-zoom` — see `llms/peers.md`
+- **Themeable via** 5 parts, 0 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`
 
 ---
@@ -35,7 +36,8 @@ browser). Does **not** extend `LyraChart` — a deliberately bespoke API.
 
 **Slots:** `data-table` — an optional consumer-provided accessible table alternative.
 
-**CSS parts:** `base`, `canvas`, `description`, `data-table`
+**CSS parts:** `base`, `canvas`, `description`, `data-table`, `error` (`role="alert"` message shown
+instead of `canvas` when the optional box-plot peer fails to load)
 
 **Themeable custom properties:** `--lr-chart-height`, `--lr-chart-grid-color`,
 `--lr-chart-tick-color`, `--lr-chart-legend-color`, `--lr-chart-tooltip-bg`,
@@ -43,8 +45,8 @@ browser). Does **not** extend `LyraChart` — a deliberately bespoke API.
 (also `getComputedStyle`-resolved on every draw), but declared in its own stylesheet, not a
 re-export: `lr-box-plot` has no `zoom`, so no `reset-zoom-button` chrome exists here.
 
-**Optional peer deps:** `@sgratzl/chartjs-chart-boxplot` (plus `chart.js` transitively, loaded
-independently of the base `chart-loader.ts`).
+**Optional peer deps:** `@sgratzl/chartjs-chart-boxplot` plus `chart.js`; Chart.js is obtained
+through the same cached `chart-loader.ts` used by `lr-chart`.
 
 ```html
 <lr-box-plot y-label="Latency (ms)"></lr-box-plot>
@@ -62,6 +64,6 @@ independently of the base `chart-loader.ts`).
   logical start in RTL, canvas tooltip/axis colors are token-driven, and animation is disabled
   under reduced motion.
 - If `@sgratzl/chartjs-chart-boxplot` fails to load, the component warns to the console and
-  resolves to no chart rather than throwing.
+  fails closed with a localized `role="alert"` error part rather than leaving a blank canvas.
 
 ---

package/llms/components/lr-branch-picker.md

@@ -6,6 +6,7 @@
 - **Class** `LyraBranchPicker`, also available unregistered from `@aceshooting/lyra-ui/components/conversation/branch-picker/branch-picker.class.js`
 - **Family** `components/conversation/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 6 parts, 0 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`
 
 ---
@@ -30,3 +31,7 @@ branch content.
 **CSS parts:** `base` (the group wrapper, `role="group"`), `previous-button`, `next-button`,
 `previous-glyph` and `next-glyph` (the chevron inside each button — target these to swap the
 arrow without restyling the button), and `position` (the visible "2 / 5" text).
+
+**Additional API surface:**
+
+- `click()` — Activates the currently enabled chevron, matching a click on the shadow control.

package/llms/components/lr-breadcrumb-item.md

@@ -6,6 +6,7 @@
 - **Class** `LyraBreadcrumbItem`, also available unregistered from `@aceshooting/lyra-ui/components/layout/breadcrumb/breadcrumb-item.class.js`
 - **Family** `components/layout/` — see `llms/index.md` for its siblings
 - **Optional peers** none
+- **Themeable via** 2 parts, 1 custom property — see this component's own `@csspart`/`@cssprop` list below
 - **Documented with** `lr-breadcrumb` (same section below)
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
@@ -37,3 +38,7 @@ set on the item, on `<lr-breadcrumb>`, or on any ancestor above the trail:
 `::part()`), so tinting the current item previously meant overriding the library-wide
 `--lr-color-text-quiet` token and repainting everything else that read it. Unset, it falls back to
 that token.
+
+**Additional API surface:**
+
+- `part="separator"` — Decorative separator shown before non-first items.