@aceshooting/lyra-ui 6.2.0 → 7.0.0

package/llms/components/lr-highlight-layer.md

@@ -6,7 +6,7 @@
 - **Class** `LyraHighlightLayer`, also available unregistered from `@aceshooting/lyra-ui/components/viewers/highlight-layer/highlight-layer.class.js`
 - **Family** `components/viewers/` — 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
+- **Themeable via** 5 parts, 11 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`
 
 ---
@@ -28,5 +28,19 @@ re-click of the same source citation).
 **Events:** `lr-highlight-activate` — a rect was activated (click, or Enter/Space while focused).
 `detail: { id }`.
 
-**CSS parts:** `base` (the absolutely-positioned overlay, inset 0) and `rect` (one highlight
-rectangle; carries `data-tone`/`data-active`/`data-flash` state attributes).
+**CSS parts:** `base` (the absolutely-positioned overlay, inset 0), `rect` (one visual highlight
+rectangle; carries `data-tone`/`data-active`/`data-flash` state attributes), and `rect-target`
+(transparent activation geometry with a minimum pointer/focus area independent of the visual
+rectangle). When more than one logical highlight would create overlapping minimum hit areas, the
+individual targets are replaced by `highlight-actions` (a non-overlapping action list) containing
+one `highlight-action` button per rendered highlight.
+
+**Themeable custom properties:**
+`--lr-highlight-layer-accent-background`, `--lr-highlight-layer-accent-outline`,
+`--lr-highlight-layer-success-background`, `--lr-highlight-layer-success-outline`,
+`--lr-highlight-layer-warning-background`, `--lr-highlight-layer-warning-outline`,
+`--lr-highlight-layer-danger-background`, `--lr-highlight-layer-danger-outline`,
+`--lr-highlight-layer-neutral-background`, and `--lr-highlight-layer-neutral-outline` control each
+tone independently, defaulting to the corresponding Lyra quiet background and foreground tokens.
+`--lr-highlight-layer-flash-background` controls the temporary flash state (default
+`--lr-color-brand`).

package/llms/components/lr-icon-button.md

@@ -6,7 +6,7 @@
 - **Class** `LyraIconButton`, also available unregistered from `@aceshooting/lyra-ui/components/forms/icon-button/icon-button.class.js`
 - **Family** `components/forms/` — see `llms/index.md` for its siblings
 - **Optional peers** none
-- **Themeable via** 2 parts, 5 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **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`
 
 ---
@@ -29,6 +29,12 @@ With neither `accessibleLabel` nor `label` set, the name falls back to the local
 app-wide with `registerLyraLocale()` (see `llms/shared.md`); don't rely on the fallback for a
 button whose purpose isn't generic.
 
+Host `aria-haspopup` and `aria-expanded` values are forwarded reactively to the shadow-internal
+native button. Host `aria-controls` targets in the host's own root are resolved through the
+reflected element-reference API, so using `<lr-icon-button slot="trigger">` inside `<lr-menu>`
+exposes the menu relationship and expanded state on the element that actually receives focus;
+browsers without that API retain the forwarded string attribute as a best-effort fallback.
+
 **Methods:** `focus(options?)`, `blur()` — forward to the native button. `click()` also forwards to
 the native button, activating it — including this component's own `type="submit"`/`type="reset"`
 handling, since the click goes through the same `<button>` the pointer/keyboard path does.
@@ -67,8 +73,10 @@ above 24px — see `llms/shared.md`. `--lr-icon-button-radius` (default `--lr-ra
 `--lr-button-radius` pattern; `lr-icon-button` has no `size` tiers, so there is no per-tier gap
 counterpart to it. `--lr-icon-button-background` (default `transparent`) tints the
 `[part='button']` background, `--lr-icon-button-background-hover` (default `--lr-color-surface`)
-its hover-state background, and `--lr-icon-button-color` (default `inherit`) its icon/text color —
-the same per-component indirection `lr-button`'s `--lr-button-fill`/`--lr-button-on-fill` provide,
-letting you tint a single button without a `::part(button)` rule. Left unset, each falls back to
-today's value, so rendering is unchanged. There is deliberately no border-color token:
-`[part='button']` sets `border: 0`, so a border color could never render.
+its hover-state background, `--lr-icon-button-color` (default `inherit`) its icon/text color,
+`--lr-icon-button-color-hover` (default `var(--lr-icon-button-color, inherit)`) its hover-state
+foreground, and `--lr-icon-button-border` (default `0`) the complete native-button border
+shorthand. These are the same per-component indirection `lr-button`'s
+`--lr-button-fill`/`--lr-button-on-fill` provide, letting a single button be bordered and tinted
+without a `::part(button)` rule. Left unset, each falls back to the original value, so rendering is
+unchanged.

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

@@ -25,6 +25,8 @@ Before/after comparison surface with two named slots and a keyboard-accessible n
 **Events:** `lr-position-change` (`detail: { position }`), plus composed `focus` and `blur` events
 from the internal range handle.
 
+**Methods:** `focus(options?)`, `blur()`, and `click()` forward to the internal range handle.
+
 **Slots:** `before`, `after`.
 
 **CSS parts:** `base`, `before`, `after`, `divider`, and `handle`.

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

@@ -6,7 +6,7 @@
 - **Class** `LyraImageViewer`, also available unregistered from `@aceshooting/lyra-ui/components/media/image-viewer/image-viewer.class.js`
 - **Family** `components/media/` — see `llms/index.md` for its siblings
 - **Optional peers** none
-- **Themeable via** 13 parts, 3 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 13 parts, 13 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`
 
 ---
@@ -47,9 +47,15 @@ mode is on. The toggle carries its own glyph in `--lr-color-text`, so keep a 4.5
 when overriding the background. `--lr-image-viewer-highlight-active-color` (default
 `var(--lr-color-brand)`) — the outline of the `[part='highlight']` matching `activeHighlightId`,
 independent of the per-tone border colors, so the active box stays distinguishable whatever tone it
-carries. All three are declared as inline `var()` fallbacks at the point of use rather than on
-`:host`, so each can be set on the element *or on any ancestor*: `::part(highlight)[data-active]` is
-invalid CSS — Shadow Parts forbids an attribute selector after `::part()` — which previously left
-overriding the library-wide `--lr-color-brand`/`--lr-color-brand-quiet` tokens as the only lever,
-repainting every other element that read them. Unset, each falls back to the token its rule used
-before.
+carries. Highlight tone styling is exposed through `--lr-image-viewer-highlight-border`,
+`--lr-image-viewer-highlight-bg`, and the tone-specific
+`--lr-image-viewer-highlight-success-border`, `--lr-image-viewer-highlight-success-bg`,
+`--lr-image-viewer-highlight-warning-border`, `--lr-image-viewer-highlight-warning-bg`,
+`--lr-image-viewer-highlight-danger-border`, `--lr-image-viewer-highlight-danger-bg`,
+`--lr-image-viewer-highlight-neutral-border`, and `--lr-image-viewer-highlight-neutral-bg`
+properties. These properties are declared as inline `var()` fallbacks at the point of use rather
+than on `:host`, so each can be set on the element *or on any ancestor*:
+`::part(highlight)[data-active]` is invalid CSS — Shadow Parts forbids an attribute selector after
+`::part()` — which previously left overriding the library-wide
+`--lr-color-brand`/`--lr-color-brand-quiet` tokens as the only lever, repainting every other
+element that read them. Unset, each falls back to the token its rule used before.

package/llms/components/lr-include.md

@@ -46,7 +46,8 @@ operate on the included text.
   `'blocked-url'` (`src` failed the allowlist; `fetch()` never ran), `'network'` (`fetch()` rejected),
   `'http'` (response not `ok`; `status` carries the code), `'missing-sanitizer'` (the optional
   `dompurify` peer failed to load), or `'resource-too-large'` (the body exceeded the shared 25 MB
-  cap). `status` is `0` for every reason but `'http'`.
+  cap). Non-HTTP reasons use status `0`; `'http'` normally carries the response code, but an opaque
+  `mode="no-cors"` response is also classified as `'http'` with status `0`.
 
 **Slots:** default — fallback content shown until (or unless) a fetch succeeds. It is overwritten by
 the sanitized fragment on success, and left untouched on failure (as is any previously successful
@@ -54,6 +55,6 @@ include).
 
 **CSS parts:** `base` — the `display: contents` wrapper around the default slot.
 
-Deviates from the shared degraded-render contract: an absent `dompurify` fires
-`lr-include-error` with `reason: 'missing-sanitizer'` and leaves the existing content in place —
-unsanitized markup is never transcluded.
+An absent `dompurify` fails closed: it fires `lr-include-error` with
+`reason: 'missing-sanitizer'` and leaves the existing content in place — unsanitized markup is
+never transcluded.

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

@@ -6,7 +6,7 @@
 - **Class** `LyraIngestionQueue`, also available unregistered from `@aceshooting/lyra-ui/components/retrieval/ingestion-queue/ingestion-queue.class.js`
 - **Family** `components/retrieval/` — see `llms/index.md` for its siblings
 - **Optional peers** none
-- **Themeable via** 16 parts, 1 custom property — see this component's own `@csspart`/`@cssprop` list below
+- **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`
 
 ---
@@ -49,8 +49,10 @@ Both `RetryEventDetail` and `CancelEventDetail` come from `@aceshooting/lyra-ui/
 per-item stage label), `item-progress`,
 `item-chunk-count`, `item-embedding-status` (the "N of M chunks embedded" text, only once both
 `chunkCount` and `embeddedChunkCount` are set), `item-attempts` (only once `attempts > 0`),
-`item-error` (only for `stage="failed"` with `error` set), `item-actions`, `retry-button`,
-`cancel-button`, `empty`.
+`item-error` (only for `stage="failed"` with `error` set), `failure-live` (the visually hidden
+assertive region that announces only failures added or transitioned after mount; historical failed
+rows remain visible without being re-announced), `item-actions`, `retry-button`, `cancel-button`,
+`empty`.
 
 In virtualized mode (at or above `virtualizeThreshold`) the rows live in the internal
 `lr-virtual-list`'s shadow root, and `item`, `item-header`, `item-name`, `item-progress`,

package/llms/components/lr-input.md

@@ -36,8 +36,9 @@ form-associated via the same `FormAssociated` mixin as `lr-textarea`. Ships the
 - `inputMode: string = ''` (attribute `inputmode`) / `enterKeyHint: string = ''` (attribute
   `enterkeyhint`) — these four are forwarded verbatim to the native input; an empty string omits
   the attribute entirely
-- `min?: number` / `max?: number` (attributes `min`/`max`) / `step?: number | 'any'` (attribute
-  `step`, accepts the native `'any'` value alongside a number) — forwarded verbatim to the native
+- `min?: number | string` / `max?: number | string` (attributes `min`/`max`) /
+  `step?: number | 'any'` (attribute `step`, accepts the native `'any'` value alongside a number)
+  — forwarded verbatim to the native
   input and validated by it. Intended for `type="number"`; `step` is equally meaningful on
   `type="time"`. On `lr-input` itself the `min`/`max` *attributes* are number-converted, so a
   non-numeric bound only survives a direct property assignment; the declared type also admits a
@@ -138,3 +139,7 @@ Several controls expose the same pair: a per-`size` `*-min-height` **floor**, an
 - An empty value is never `tooShort` and never a `patternMismatch` — both native constraints skip
   the empty string, and `required` is what rejects it.
 - `type="password"` always renders the `password-toggle` button; there is no separate opt-out.
+
+**Additional API surface:**
+
+- `click()` — Activates the internal input.

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

@@ -6,7 +6,7 @@
 - **Class** `LyraJsonViewer`, also available unregistered from `@aceshooting/lyra-ui/components/utility/json-viewer/json-viewer.class.js`
 - **Family** `components/utility/` — see `llms/index.md` for its siblings
 - **Optional peers** none
-- **Themeable via** 8 parts, 3 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 9 parts, 8 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,8 +35,10 @@ stack overflow on cyclic `data`.
 **Methods:** `runSearch(query)` sets the declarative `search` property and awaits the recompute,
 resolving the match count — named distinctly from `search` because a class member can't share a name
 with a reactive property. `searchNext()`/`searchPrevious()` advance/step back a match cursor
-(wrapping) and scroll the active match into view, resolving `false` when there are no matches.
-`clearSearch()` resets `search` to `''`, clearing all matches and the cursor.
+(wrapping), reveal that selected match even when one of its ancestors was explicitly collapsed,
+mark it as the active `aria-current` result, announce its position, and scroll it into view;
+they resolve `false` when there are no matches. `clearSearch()` resets `search` to `''`, clearing all
+matches and the cursor.
 
 **Events:** `lr-copy` (`detail: { text: string }`) — fired by the top-level copy button or a
 per-node one. Fires even when `navigator.clipboard` is unavailable or the write silently failed
@@ -67,7 +69,13 @@ until `max-height` is set), `--lr-json-viewer-font` (default `var(--lr-font-mono
 `--lr-json-viewer-match-bg` (default `var(--lr-color-warning-quiet)`) — background, and surrounding
 box-shadow, of a key/value that currently matches `search`. Component-scoped indirection over the
 shared `--lr-color-warning-quiet` token, so a consumer can retheme just this search-match highlight
-without repainting every other warning-toned surface that reads the same shared token. Plus shared
+without repainting every other warning-toned surface that reads the same shared token;
+`--lr-json-viewer-active-outline` (default `var(--lr-focus-ring-color)`) — outline color for the
+current imperative search match; `--lr-json-viewer-string-color` (default
+`var(--lr-color-success)`), `--lr-json-viewer-number-color` (default `var(--lr-color-brand)`),
+`--lr-json-viewer-boolean-color` (default `var(--lr-color-warning)`), and
+`--lr-json-viewer-null-color` (default `var(--lr-color-text-quiet)`) — per-value-type color hooks.
+Plus shared
 tokens `--lr-color-border/-surface/-text/-text-quiet/-brand/-brand-quiet/-success/-warning/-warning-quiet`,
 `--lr-radius`, `--lr-space-xs/-s/-l`, `--lr-focus-ring-width/-color/-offset`,
 `--lr-transition-fast`.
@@ -93,9 +101,11 @@ html`<lr-json-viewer .data=${apiResponse} copyable max-height="24rem" search=${q
   binding, never as a plain HTML attribute.
 - Search highlighting auto-expands only the *ancestors* of a match, not the whole tree — a
   non-matching sibling subtree elsewhere stays collapsed (or expanded) exactly as it already was.
-- An explicit per-node expand/collapse (from clicking a node's `toggle` button) permanently overrides
-  both `collapsedDepth` and any search-driven auto-expand for that path, until `data` is reassigned
-  with a different shape.
+- An explicit per-node expand/collapse (from clicking a node's `toggle` button) overrides
+  `collapsedDepth` and declarative search-driven auto-expansion for that path. Imperative
+  `searchNext()`/`searchPrevious()` navigation may reopen the ancestors of the selected result so
+  the active match is never hidden; otherwise the override persists until `data` is reassigned with
+  a different shape.
 - Per-node copy buttons call `stopPropagation()` on click so clicking one doesn't also toggle the
   row's expand/collapse state.
 

package/llms/components/lr-kbd.md

@@ -31,11 +31,13 @@ string. First-party invention (no Web Awesome equivalent).
   (single letters/digits upper-cased).
 
 **Exported types/functions (also directly usable standalone):** `KbdKeyLabel { visual: string;
-word: string }` — one resolved token's rendered glyph and spelled-out word.
-`shortcutTokenLabel(rawToken: string, isMac: boolean): KbdKeyLabel` — resolves a single token,
-parameterized on `isMac` so both platform branches are unit-testable without spoofing `navigator`.
-`parseShortcut(keys: string, isMac: boolean): KbdKeyLabel[]` — splits and resolves a full `keys`
-string.
+word: string }` — one resolved token's rendered glyph and spelled-out word; `KbdLocalize = (key:
+string, fallback: string) => string`.
+`shortcutTokenLabel(rawToken: string, isMac: boolean, localize?: KbdLocalize): KbdKeyLabel`
+resolves a single token, parameterized on `isMac` so both platform branches are unit-testable
+without spoofing `navigator`; the optional callback localizes spoken key names.
+`parseShortcut(keys: string, isMac: boolean, localize?: KbdLocalize): KbdKeyLabel[]` splits and
+resolves a full `keys` string with the same optional localization callback.
 
 **Events:** none — purely presentational.
 

package/llms/components/lr-known-date.md

@@ -102,3 +102,7 @@ The two height knobs work as a pair on `[part='field-input']`, the same way
   required date reports `badInput` instead.
 - The host carries a `:state(blank)` custom state whenever `value === ''`, and `data-invalid` only
   once touched (first blur out of the whole control) and actually invalid.
+
+**Additional API surface:**
+
+- `click()` — Activates the first native field in locale order.

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

@@ -6,7 +6,7 @@
 - **Class** `LyraLocalePicker`, also available unregistered from `@aceshooting/lyra-ui/components/forms/locale-picker/locale-picker.class.js`
 - **Family** `components/forms/` — see `llms/index.md` for its siblings
 - **Optional peers** none
-- **Themeable via** 11 parts, 6 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 11 parts, 12 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`
 
 ---
@@ -89,3 +89,12 @@ peer warning duplication; `lr-flag` itself already logs one) when the optional
   or `lr-combobox` instead.
 - arrow-key navigation is vertical-only (Home/End/ArrowUp/ArrowDown); there is no
   ArrowLeft/ArrowRight remap under RTL, since there is no horizontal axis to remap.
+
+**Additional API surface:**
+
+- `--lr-locale-picker-gap` — Trigger and option child gap. Default: `var(--lr-space-xs)`.
+- `--lr-locale-picker-radius` — Trigger/listbox/option corner radius. Default: `var(--lr-radius)`.
+- `--lr-locale-picker-trigger-hover-bg` — Trigger hover background. Default: `var(--lr-color-brand-quiet)`.
+- `--lr-locale-picker-open-border-color` — Open trigger border color. Default: `var(--lr-color-brand)`.
+- `--lr-locale-picker-option-selected-border-color` — Selected option border. Default: `var(--lr-color-brand)`.
+- `--lr-locale-picker-option-selected-color` — Selected option text. Default: `var(--lr-color-brand)`.

package/llms/components/lr-map.md

@@ -74,13 +74,19 @@ not installed)
 **Themeable custom properties:** shared tokens only — `--lr-space-xs/-s`, `--lr-color-surface`,
 `--lr-color-border`, `--lr-shadow`, `--lr-radius`.
 
-**Optional peer deps:** `maplibre-gl` (lazy-loaded; consumer must **separately** `import
-'maplibre-gl/dist/maplibre-gl.css'` once — the component does not do this for you).
+**Optional peer deps:** `maplibre-gl` (lazy-loaded). MapLibre v6 is ESM-only and requires WebGL2.
+The consumer must **separately** import `maplibre-gl/dist/maplibre-gl.css` and configure the v6
+module-worker URL for its bundler once — the component cannot choose a bundler-specific worker URL.
+For Vite:
 
 ```html
 <lr-map center="[2.35, 48.85]" zoom="10"></lr-map>
-<script>
+<script type="module">
+  import { setWorkerUrl } from 'maplibre-gl';
+  import workerUrl from 'maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url';
   import 'maplibre-gl/dist/maplibre-gl.css';
+  setWorkerUrl(workerUrl);
+
   const m = document.querySelector('lr-map');
   m.choropleth = {
     sourceId: 'regions',
@@ -94,6 +100,10 @@ not installed)
 </script>
 ```
 
+Webpack, esbuild, Rollup, and direct-browser ESM use different worker URL forms; use MapLibre's ESM
+installation guide for the matching setup:
+https://maplibre.org/maplibre-gl-js/docs/#esm.
+
 **Known gotchas:**
 - clearing or swapping the choropleth no longer leaks the old layer: setting `choropleth =
   undefined`, or changing `choropleth.sourceId` to a different value, now calls `removeLayer`/

package/llms/components/lr-markdown-core.md

@@ -6,7 +6,7 @@
 - **Class** `LyraMarkdownCore`, also available unregistered from `@aceshooting/lyra-ui/components/conversation/markdown/markdown-core.class.js`
 - **Family** `components/conversation/` — see `llms/index.md` for its siblings
 - **Optional peers** `dompurify`, `katex`, `marked`, `shiki` — see `llms/peers.md`
-- **Themeable via** 11 parts, 1 custom property — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 11 parts, 8 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`
 
 ---
@@ -77,4 +77,14 @@ differently on a wrapped line.
 </script>
 ```
 
+**Additional API surface:**
+
+- `--lr-markdown-highlight-accent-bg` — Accent highlight fill. Default: `var(--lr-color-brand-quiet)`.
+- `--lr-markdown-highlight-success-bg` — Success highlight fill. Default: `var(--lr-color-success-quiet)`.
+- `--lr-markdown-highlight-warning-bg` — Warning highlight fill. Default: `var(--lr-color-warning-quiet)`.
+- `--lr-markdown-highlight-danger-bg` — Danger highlight fill. Default: `var(--lr-color-danger-quiet)`.
+- `--lr-markdown-highlight-neutral-bg` — Neutral highlight fill. Default: `var(--lr-color-surface)`.
+- `--lr-markdown-highlight-active-bg` — Active highlight fill. Default: `var(--lr-color-brand-quiet)`.
+- `--lr-markdown-highlight-active-outline-color` — Active highlight outline. Default: `var(--lr-color-brand)`.
+
 ---

package/llms/components/lr-markdown.md

@@ -6,7 +6,7 @@
 - **Class** `LyraMarkdown`, also available unregistered from `@aceshooting/lyra-ui/components/conversation/markdown/markdown.class.js`
 - **Family** `components/conversation/` — see `llms/index.md` for its siblings
 - **Optional peers** `dompurify`, `katex`, `marked`, `shiki` — see `llms/peers.md`
-- **Themeable via** 11 parts, 2 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 11 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`
 
 ---
@@ -181,4 +181,14 @@ restart at the beginning of each visual line, so a wrapped line's tabs land diff
   HTML `marked` produces from `content` completely unsanitized, so untrusted `content` must never be
   paired with `sanitize="false"`.
 
+**Additional API surface:**
+
+- `--lr-markdown-highlight-accent-bg` — Accent highlight fill. Default: `var(--lr-color-brand-quiet)`.
+- `--lr-markdown-highlight-success-bg` — Success highlight fill. Default: `var(--lr-color-success-quiet)`.
+- `--lr-markdown-highlight-warning-bg` — Warning highlight fill. Default: `var(--lr-color-warning-quiet)`.
+- `--lr-markdown-highlight-danger-bg` — Danger highlight fill. Default: `var(--lr-color-danger-quiet)`.
+- `--lr-markdown-highlight-neutral-bg` — Neutral highlight fill. Default: `var(--lr-color-surface)`.
+- `--lr-markdown-highlight-active-bg` — Active highlight fill. Default: `var(--lr-color-brand-quiet)`.
+- `--lr-markdown-highlight-active-outline-color` — Active highlight outline. Default: `var(--lr-color-brand)`.
+
 ---

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

@@ -0,0 +1,51 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/agent-tools.md — do not edit this file. -->
+
+# `lr-mcp-app`
+
+- **Import** `import '@aceshooting/lyra-ui/components/agent-tools/mcp-app/mcp-app.js';` (registers the tag; side-effect import)
+- **Class** `LyraMcpApp`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/mcp-app/mcp-app.class.js`
+- **Family** `components/agent-tools/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Themeable via** 4 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-mcp-app`
+
+Sandbox host for executable MCP App-style resources. Inline documents run in a unique-origin iframe
+with injected CSP; remote documents are URL-validated. The frame can only request tool calls,
+messages, navigation, logs, and clamped resizing through typed events. Capabilities are denied
+unless explicitly enabled in `resource.permissions`.
+
+**Properties:**
+
+- `resource: McpAppResource | null = null` (attribute: false) — either inline `html` or a safe
+  remote `src`, plus the required logical `uri`. `McpAppResource = { uri: string; title?: string;
+  html?: string; src?: string; csp?: McpAppCsp; permissions?: McpAppPermissions; metadata?:
+  Record<string, unknown> }`. CSP domain arrays accept HTTP(S) origins only. Permissions are
+  optional booleans for camera, microphone, geolocation, clipboard read, and clipboard write.
+- `height: number = 320`, `maxHeight: number = 800` (attribute `max-height`) — requested and maximum
+  frame heights in pixels; runtime values and resize requests clamp to 120–10,000.
+- `label: string = ''`; `accessibleLabel: string | null = null` (attribute `aria-label`) — frame
+  title precedence is host `aria-label`, `label`, resource title, then the localized fallback.
+
+**Methods:** `postHostContext(context: unknown): void` posts host state into the active frame;
+`postToolResult(requestId: string, result?: unknown, error?: string): void` resolves a prior tool
+request. Both are no-ops before a frame exists.
+
+**Exported types:** `McpAppResource`, `McpAppCsp`, `McpAppPermissions`,
+`McpAppToolCallDetail`, and `LyraMcpAppEventMap`.
+
+**Events:** `lr-mcp-ready` (`{ uri }`), `lr-mcp-tool-call` (`{ requestId?, name, args }`),
+`lr-mcp-send-message` (`{ message }`), `lr-mcp-open-link` (`{ href }`), `lr-mcp-log`
+(`{ level, value }`), and `lr-mcp-resize` (`{ height }`). These are host-authorized requests; the
+component does not execute tools, send messages, or navigate itself.
+
+**CSS parts:** `base`, `frame`, `loading`, `error`.
+
+**Slots:** none. **Optional peer deps:** none.
+
+```ts
+import '@aceshooting/lyra-ui/components/agent-tools/mcp-app/mcp-app.js';
+```

package/llms/components/lr-media-card.md

@@ -52,6 +52,9 @@ drop-in still does something useful, but `lr-open` fires first — a host callin
 `preventDefault()` on it suppresses that default download/open so it can substitute its own
 handling.
 
+**Methods:** `focus(options?)`, `blur()`, and `click()` forward to the primary action for the
+current media kind.
+
 **Slots:** none.
 
 **CSS parts:** `base` (a `<button>` for `kind="image"`, a plain wrapper `<div>` for `kind="video"`,

package/llms/components/lr-mention-popover.md

@@ -15,10 +15,11 @@
 
 A caret-anchored, keyboard-navigable popover for `@`-mention and `/`-slash-command autocomplete
 inside a plain-text `<textarea>`/`<input>` the host owns. First-party invention (no Web Awesome
-equivalent). It never takes DOM focus itself — the host's own input keeps focus, and this
-component conveys the active row via `activeDescendantId` for the host to apply as its own
-input's `aria-activedescendant`, the same pattern `<lr-select>`/`<lr-combobox>` use for their
-own listbox.
+equivalent). On platforms accepting cross-root ARIA element reflection, the host's own input keeps
+focus and `syncActiveDescendant()` points it at the active option. Where that reference is rejected,
+`focusActiveOption()` moves real focus into this component's shadow listbox so the focus owner and
+option share one tree scope. A string `aria-activedescendant` cannot resolve from a host input in
+the document into an option in this component's shadow root.
 
 **Properties:**
 - `anchor?: HTMLElement` (attribute: false) — the element to position the popup relative to. A
@@ -38,18 +39,26 @@ own listbox.
 - `filteredItems: MentionItem[]` — read-only getter; `items` filtered by `query` via `filter` (or
   the built-in default). Empty `query` returns `items` unfiltered.
 - `activeDescendantId: string | null` — read-only getter; the `id` of the currently-highlighted
-  row, or `null` while closed or when `filteredItems` is empty.
-- `listboxId: string` — read-only getter; the `id` of the `role="listbox"` element, for a host that
-  also wants to wire `aria-controls`.
-
-**Methods:** `handleKeyDown(e: KeyboardEvent): boolean` — the host's own text-control `keydown`
-handler calls this while the popover is open. Handles `ArrowDown`/`ArrowUp` (moves the highlight) and
-`Enter`/`Tab` (commits the highlighted row) — both pairs return `false` with no `preventDefault()`
-when `filteredItems` is empty, letting the keystroke fall through to the host's own control unchanged
-(e.g. the textarea's caret still moves to the next line on ArrowDown when there's nothing to
-navigate); `Escape` always closes with no selection and returns `true`. Returns `true` whenever the
-key was intercepted (`preventDefault()` already called) and the host should not also act on it,
-`false` otherwise (including for any key this method doesn't recognize).
+  internal row, or `null` while closed or when `filteredItems` is empty. Useful for diagnostics and
+  same-tree consumers; do not copy it to an external control as a string IDREF.
+- `activeDescendantElement: HTMLElement | null` — read-only getter; the highlighted shadow option
+  for the platform's element-reference ARIA API.
+- `listboxId: string` — read-only getter; the internal `id` of the `role="listbox"` element. Like
+  `activeDescendantId`, it cannot form a cross-shadow string IDREF from a host input.
+
+**Methods:**
+- `handleKeyDown(e: KeyboardEvent): boolean` — the host's own text-control `keydown` handler calls
+  this while the popover is open. Handles `ArrowDown`/`ArrowUp` (moves the highlight) and
+  `Enter`/`Tab` (commits the highlighted row) — both pairs return `false` with no
+  `preventDefault()` when `filteredItems` is empty, letting the keystroke fall through to the
+  host's own control unchanged. `Escape` closes with no selection. Returns `true` whenever the key
+  was intercepted and `false` for keys the method does not recognize.
+- `syncActiveDescendant(control: HTMLElement): boolean` — clears any string
+  `aria-activedescendant`, then applies `ariaActiveDescendantElement` when the platform accepts the
+  cross-root reference. Returns whether that reference was accepted.
+- `focusActiveOption(): Promise<boolean>` — same-tree fallback after a consumed navigation key
+  when `syncActiveDescendant()` returns `false`. Focuses the active option, lets the popover handle
+  subsequent navigation, and restores focus to `anchor` when the popover closes.
 
 **Exported types:** `MentionItem { id: string; label: string; description?: string; icon?: string
 }`; `MentionFilter = (item: MentionItem, query: string) => boolean`; `MentionSelectDetail { id:
@@ -91,7 +100,13 @@ available space. See `lr-tour` for the shared-clamp note.
   const popover = document.getElementById('mentions');
 
   textarea.addEventListener('keydown', (e) => {
-    if (popover.open && popover.handleKeyDown(e)) return; // consumed
+    if (popover.open && popover.handleKeyDown(e)) {
+      if (!popover.syncActiveDescendant(textarea) &&
+          (e.key === 'ArrowDown' || e.key === 'ArrowUp')) {
+        void popover.focusActiveOption();
+      }
+      return;
+    }
   });
   textarea.addEventListener('input', () => {
     popover.anchor = textarea;
@@ -101,6 +116,7 @@ available space. See `lr-tour` for the shared-clamp note.
     ];
     popover.query = 'a'; // detected since the trigger character
     popover.open = true;
+    popover.updateComplete.then(() => popover.syncActiveDescendant(textarea));
   });
 
   popover.addEventListener('lr-mention-select', (e) => {
@@ -111,11 +127,11 @@ available space. See `lr-tour` for the shared-clamp note.
 
 Integration is entirely the host's responsibility: detect a mention/command trigger in the host's
 own `input` handling, set `anchor`/`items`/`query` and flip `open = true`, forward every `keydown`
-through `handleKeyDown()` while open, and keep the host's own input's `aria-activedescendant` (and
-optionally `aria-controls`, via `listboxId`) in sync with `activeDescendantId`. Setting `open =
-false` whenever the query stops looking like an active mention context (a space typed, the trigger
-deleted, the input blurred, …) is also the host's job — `lr-mention-close` fires automatically
-from that, there is no separate "tell it to close" call needed.
+through `handleKeyDown()` while open, and call `syncActiveDescendant()` after opening and after each
+consumed navigation key. If it returns `false`, call `focusActiveOption()` after the first consumed
+ArrowUp/ArrowDown so the fallback owns navigation from then on. Setting `open = false` whenever the
+query stops looking like an active mention context (a space typed, the trigger deleted, the input
+blurred, …) is also the host's job — `lr-mention-close` fires automatically from that.
 
 Positioning measures exactly where the caret currently paints via a hidden-mirror-element technique
 (`caretClientRect()`) and positions against that single point with `internal/positioner.js`'s
@@ -127,6 +143,9 @@ fresh `query` is the proxy for "the caret may have moved").
 - a host-level `aria-label` attribute on `<lr-mention-popover>` now takes priority over `label`
   (and its localized default) when resolving `[part="listbox"]`'s accessible name — previously it
   was silently ignored. Matches the same fallback on `<lr-combobox>`/`<lr-table>`.
+- Never copy `activeDescendantId` or `listboxId` onto a document-owned control as a string ARIA
+  IDREF; shadow-root IDs are outside that control's tree scope. Use `syncActiveDescendant()` and its
+  `focusActiveOption()` fallback.
 - The popover opens pre-highlighted on the top match (index 0), unlike `<lr-combobox>`'s own
   listbox which opens with nothing highlighted (`-1`) — a bare Enter right after opening commits
   immediately.

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

@@ -66,8 +66,12 @@ returning to the trigger)
 **Slots:** `trigger` (the consumer's own trigger element — first assigned element wins if several
 are assigned; enhanced imperatively with `aria-haspopup="menu"`/`aria-expanded`/`aria-controls`
 since those attributes belong on the actual interactive trigger, which lives outside this
-component's shadow root), default (`<lr-menu-item>` elements, plus optionally plain `<hr>`
-dividers between groups — native `<hr>` already carries an implicit `separator` role),
+component's shadow root. `aria-controls` targets the `lr-menu` host, which receives a stable
+generated id only when the consumer did not provide one, rather than the shadow-private list id.
+`lr-button`/`lr-icon-button` forward the popup/expanded values to their focused shadow-internal
+native control and resolve the controls element-reference across their shadow boundary), default
+(`<lr-menu-item>` elements, plus optionally plain `<hr>` dividers — native `<hr>` already carries
+an implicit `separator` role),
 `header` and `footer` (composed, deliberately non-menu-item content — a filter/search field, a
 section title, an "Apply"/"Done" button, a count — rendered above/below the items inside
 `[part="popup"]` but **outside** the `role="menu"` list. Both collapse to no box at all while

package/llms/components/lr-menu.md

@@ -66,8 +66,12 @@ returning to the trigger)
 **Slots:** `trigger` (the consumer's own trigger element — first assigned element wins if several
 are assigned; enhanced imperatively with `aria-haspopup="menu"`/`aria-expanded`/`aria-controls`
 since those attributes belong on the actual interactive trigger, which lives outside this
-component's shadow root), default (`<lr-menu-item>` elements, plus optionally plain `<hr>`
-dividers between groups — native `<hr>` already carries an implicit `separator` role),
+component's shadow root. `aria-controls` targets the `lr-menu` host, which receives a stable
+generated id only when the consumer did not provide one, rather than the shadow-private list id.
+`lr-button`/`lr-icon-button` forward the popup/expanded values to their focused shadow-internal
+native control and resolve the controls element-reference across their shadow boundary), default
+(`<lr-menu-item>` elements, plus optionally plain `<hr>` dividers — native `<hr>` already carries
+an implicit `separator` role),
 `header` and `footer` (composed, deliberately non-menu-item content — a filter/search field, a
 section title, an "Apply"/"Done" button, a count — rendered above/below the items inside
 `[part="popup"]` but **outside** the `role="menu"` list. Both collapse to no box at all while