@aceshooting/lyra-ui 6.0.0 → 6.2.0

package/dist/theme/theme.js

@@ -0,0 +1,132 @@
+/**
+ * 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();
+}
+/**
+ * A self-contained IIFE body, safe to inline into a `<script>` tag placed before any stylesheet
+ * in `<head>`, that applies the persisted theme before first paint (avoiding a flash of the
+ * wrong theme). Deliberately a plain string (not a function) so it can be inlined without also
+ * shipping/parsing this whole module in an unbundled `<script>` context.
+ */
+export const lyraThemeBootstrap = `(function(){try{var raw=localStorage.getItem(${JSON.stringify(STORAGE_KEY)});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){}})();`;
+//# 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,29 @@
+<!-- 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, 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`
+
+---
+
+## `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' }`; `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 }`, reserved for host-controlled metric selectors) and
+`lr-run-select` (`{ runId }`).
+
+**CSS parts:** `base`, `heading`, `metrics`, `metric`, `chart`, `runs`, `runs-heading`, `run`,
+`run-label`, `run-meta`, `run-status`, `empty`.

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, 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-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`
 
 ---

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,10 @@ 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 `open` and
+`railWidthPx` to `localStorage` under `lr-app-rail:${storageKey}` and restore them on the next mount
+(mirrors `lr-split`'s `storage-key`; `mode` is breakpoint-derived and never persisted). 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 +76,9 @@ 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 `open` and `railWidthPx` to
+  `localStorage` under `lr-app-rail:${storageKey}` and restores them on the next mount. `mode` is
+  breakpoint-derived and never persisted. Unset means no persistence.
 - `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
@@ -90,9 +96,12 @@ role, matching `<lr-date-input>`'s `accessibleLabel`.
 **Events:** `lr-mode-change` (`detail: AppRailModeChangeDetail` = `{ mode: AppRailMode }`; the
 effective mode changed, whether from a breakpoint crossing or an explicit `mode` assignment — not
 fired for a redundant reassignment to the mode already in effect), `lr-toggle`
-(`detail: AppRailToggleDetail` = `{ open: boolean }`; the mobile overlay opened or closed — via the
-built-in toggle button, Escape, a backdrop click, a nav-item click while open, or a breakpoint/forced
-mode change leaving `'mobile'` while open — not fired when a consumer sets `open` directly),
+(`detail: AppRailToggleDetail` = `{ open: boolean }`; the mobile overlay is opening or closing — via
+the built-in toggle button, Escape, a backdrop click, a nav-item click while open, or a
+breakpoint/forced mode change leaving `'mobile'` while open — not fired when a consumer sets `open`
+directly. Cancelable for every trigger except the forced mode-change close, which always applies —
+vetoing that one would leave `open` stuck `true` in a mode where it's meaningless; call
+`preventDefault()` to keep the overlay as it is for the other triggers),
 `lr-rail-resize` (`detail: AppRailResizeDetail` = `{ widthPx: number }`; the `resizable` rail's
 width changed via drag or keyboard stepping — not fired when a consumer sets `railWidthPx` directly).
 

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,10 @@ 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 `open` and
+`railWidthPx` to `localStorage` under `lr-app-rail:${storageKey}` and restore them on the next mount
+(mirrors `lr-split`'s `storage-key`; `mode` is breakpoint-derived and never persisted). 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 +76,9 @@ 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 `open` and `railWidthPx` to
+  `localStorage` under `lr-app-rail:${storageKey}` and restores them on the next mount. `mode` is
+  breakpoint-derived and never persisted. Unset means no persistence.
 - `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
@@ -90,9 +96,12 @@ role, matching `<lr-date-input>`'s `accessibleLabel`.
 **Events:** `lr-mode-change` (`detail: AppRailModeChangeDetail` = `{ mode: AppRailMode }`; the
 effective mode changed, whether from a breakpoint crossing or an explicit `mode` assignment — not
 fired for a redundant reassignment to the mode already in effect), `lr-toggle`
-(`detail: AppRailToggleDetail` = `{ open: boolean }`; the mobile overlay opened or closed — via the
-built-in toggle button, Escape, a backdrop click, a nav-item click while open, or a breakpoint/forced
-mode change leaving `'mobile'` while open — not fired when a consumer sets `open` directly),
+(`detail: AppRailToggleDetail` = `{ open: boolean }`; the mobile overlay is opening or closing — via
+the built-in toggle button, Escape, a backdrop click, a nav-item click while open, or a
+breakpoint/forced mode change leaving `'mobile'` while open — not fired when a consumer sets `open`
+directly. Cancelable for every trigger except the forced mode-change close, which always applies —
+vetoing that one would leave `open` stuck `true` in a mode where it's meaningless; call
+`preventDefault()` to keep the overlay as it is for the other triggers),
 `lr-rail-resize` (`detail: AppRailResizeDetail` = `{ widthPx: number }`; the `resizable` rail's
 width changed via drag or keyboard stepping — not fired when a consumer sets `railWidthPx` directly).
 

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

@@ -0,0 +1,27 @@
+<!-- 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, 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`
+
+---
+
+## `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`.

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`
 
 ---

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`
 
 ---

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`
 
@@ -30,3 +31,6 @@ color for text and border). Set one directly on the element for a tint outside t
 `var(--lr-space-s)`), and `--lr-badge-min-height` (default `var(--lr-size-1-25rem)`) — the density
 trio each `:host([size])` rule rewrites to that step's font size, inline padding, and minimum block
 size; the `m` defaults above exactly reproduce the pre-`size` fixed badge treatment.
+`--lr-badge-radius` (default `--lr-radius-pill`) is `[part='base']`'s corner radius, retunable
+without a `::part(base)` rule and, unlike the density trio, does not vary by `size` — the same
+`--lr-button-radius` pattern; `lr-tag` inherits it unchanged, the same as `size`.

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`,
@@ -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`
 
 ---

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** 1 part, 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`
 

package/llms/components/lr-breadcrumb.md

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

package/llms/components/lr-browser-frame.md

@@ -6,6 +6,7 @@
 - **Class** `LyraBrowserFrame`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/browser-frame/browser-frame.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`
 
 ---

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

@@ -5,7 +5,8 @@
 - **Import** `import '@aceshooting/lyra-ui/components/charts/chart/bubble-chart.js';` (registers the tag; side-effect import)
 - **Class** `LyraBubbleChart`, also available unregistered from `@aceshooting/lyra-ui/components/charts/chart/bubble-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-bar-chart`, `lr-pie-chart`, `lr-doughnut-chart`, `lr-radar-chart`, `lr-polar-area-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-button-group.md

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