@aceshooting/lyra-ui 5.0.0 → 5.1.0

package/llms/components/lr-markdown.md

@@ -0,0 +1,171 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/conversation.md — do not edit this file. -->
+
+# `lr-markdown`
+
+- **Import** `import '@aceshooting/lyra-ui/components/conversation/markdown/markdown.js';` (registers the tag; side-effect import)
+- **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`
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-markdown`
+
+Sanitized Markdown-to-HTML rendering (GFM tables, fenced code blocks, links, blockquotes) built on
+two optional peer dependencies — `marked` (parsing) and `dompurify` (sanitizing) — both lazy-loaded
+independently via `markdown-loader.ts`'s `loadMarkdownDeps()` on first connect, cached per page the
+same way `chart-loader.ts`/`map-loader.ts` cache their load promise so every `<lr-markdown>`
+instance on a page shares one load. `heading`/`code`/`blockquote`/`table`/`link`/`image` tokens are
+rendered through a `marked` renderer override that injects `part="..."` attributes directly into the
+produced HTML in a single pass (no second DOM walk after insertion).
+
+Fenced code blocks are also syntax-highlighted via the same optional `shiki` peer `<lr-code-block>`
+uses, gated by `highlightCode` (default `true`). This is a pure upgrade, not a separate opt-in: it's
+already transparently gated by whether `shiki` is installed at all, so an app that never installs the
+peer sees byte-identical output to before this property existed. The very first render of any content
+is always plain text/code (identical to today's output); highlighting arrives as an asynchronous
+upgrade one render later once shiki resolves and the block's language is tokenized. No highlighting
+is attempted while `streaming` is `true` — it applies once a stream settles, adding no per-chunk cost
+while content is still arriving.
+
+**Properties:**
+- `content: string = ''` — the Markdown source to render
+- `sanitize: boolean = true` — sanitize `marked`'s HTML output with DOMPurify before rendering
+- `escapeHtml: boolean = false` (attribute `escape-html`) — when `true`, overrides `marked`'s `html`
+  renderer hook to emit the HTML-escaped source text instead of passing raw/sanitized markup through
+  — for rendering arbitrary already-written content (e.g. a historical chat/agent transcript full of
+  code/XML/HTML snippets) where a stray angle bracket should render as visible text, not a real DOM
+  element. GFM tables/lists/etc. still render normally — only raw embedded HTML is affected. `false`
+  (the default) reproduces the exact `marked`-default (sanitized-when-`sanitize`) passthrough
+  behavior.
+- `gfm: boolean = true` — GitHub-flavored Markdown (tables, strikethrough, autolinks, task lists)
+- `linkTarget: string | null = '_blank'` (attribute `link-target`) — `target` applied to every
+  rendered `<a>`, with `rel="noopener noreferrer"` always added alongside it whenever a `target` is
+  emitted. `'_blank'` (the default) preserves the original output; a falsy value (`null`, or the
+  empty string via `link-target=""`) omits `target`/`rel` entirely instead of always defaulting to
+  `_blank`, so rendered links open in the same tab
+- `internalLinkPrefix: string = ''` (attribute `internal-link-prefix`) — when set, a rendered link
+  whose `href` *attribute* (not the browser-resolved `.href` property) starts with this prefix is
+  intercepted on click and reported via `lr-link-click` instead of navigating; empty (the default)
+  means every link is treated as external
+- `headingOffset: number = 0` (attribute `heading-offset`) — added to every rendered heading's
+  source `token.depth` before emitting `<h${depth}>` (e.g. `heading-offset="2"` renders a source `#`
+  as `<h3>`); clamped to `[1, 6]` so a source `######` with a positive offset stays at `<h6>` rather
+  than overflowing past the HTML heading levels. `0` (the default) preserves the original
+  `<h${token.depth}>` output
+- `eagerLoad: boolean = false` (attribute `eager-load`) — when `true`, `connectedCallback()` skips
+  awaiting the async `loadMarkdownDeps()` import and renders synchronously if the shared
+  `marked`/`dompurify` module cache is *already* warm (e.g. an earlier `<lr-markdown>` instance on
+  the page already finished loading); falls back to the normal async path (with its brief
+  plain-text-fallback first paint) when the cache isn't warm yet. `false` (the default) is
+  byte-identical to always taking the async path
+- `streaming: boolean = false` (reflected) — marks the host `aria-busy="true"` while partial Markdown
+  is still arriving and lets consumers target `lr-markdown[streaming]`; content updates while it is
+  true are coalesced to at most one parse per animation frame, while the final `streaming=false`
+  update flushes the latest content immediately; busy state also remains true while parser
+  dependencies are loading
+- `highlightCode: boolean = true` (attribute `highlight-code`) — syntax-highlights fenced code
+  blocks via the optional `shiki` peer. `true` (the default) upgrades every fenced block once the
+  peer is available; set `false` to keep plain output even when `shiki` is installed. No effect
+  while `streaming` is `true`
+- `languages?: Record<string, ShikiLanguageInput>` (attribute: false) — same shape and purpose as
+  `<lr-code-block>`'s own `languages`: a fine-grained, explicit language-grammar bundle scoping
+  shiki's build output to just those grammars instead of its full ~200-language bundle. Forwarded
+  verbatim to `loadShikiHighlighterCore()`. Unset (the default) uses the default full-bundle loader
+- `languagesOnly: boolean = false` (attribute `languages-only`) — same purpose as
+  `<lr-code-block>`'s own `languagesOnly`: skips the default full-bundle loader entirely, so a
+  fenced block whose language isn't in `languages` falls back to plain unhighlighted text rather
+  than reaching for the full bundle. No effect unless `languages` is also set
+- `headingAnchors: boolean = false` (attribute `heading-anchors`) — stamps a computed
+  GitHub-slugger-style slug as `id` on every rendered heading.
+- `math: boolean = false` — renders `$inline$` and `$$block$$` TeX via the optional `katex` peer,
+  lazy-loaded the same way as `marked`/`dompurify`/`shiki`.
+- `anchorKinds: readonly ('fragment' | 'text-quote')[]` (readonly) — the anchor kinds this
+  component resolves for the shared anchor-target contract.
+
+**Methods:** `getHeadingTree()` returns the document-ordered heading outline (`{ level, text, slug
+}[]`) computed on every parse, regardless of `headingAnchors`.
+
+**Events:**
+- `lr-link-click` (`detail: { href: string; internal: true }`) — fired, with the click prevented,
+  when a rendered link's `href` starts with `internal-link-prefix`; ordinary external links navigate
+  normally and never fire this
+- `lr-render-error` (`detail: { error: unknown }`) — rendering fell back to plain text (see the
+  fallback matrix below), or `math` is set but the `katex` peer isn't installed
+- `lr-highlight-activate` (`detail: { id: string }`) — a painted `text-quote` highlight was clicked
+- `lr-text-select` (`detail: { text: string; anchor: LyraAnchor | null; rects: DOMRect[] }`) — a text
+  selection inside the rendered content ended; `anchor` is a `text-quote` anchor scoped to the
+  rendered content, or `null` when the selection couldn't be anchored
+- `lr-anchor-result` (`detail: { found: boolean }`) — fired after an `anchor` property assignment or
+  a `scrollToAnchor()` call is applied (the shared anchor-target contract)
+
+**Slots:** none — content comes from the `content` property, not light-DOM children.
+
+**CSS parts:** `content` (the wrapper around the rendered or plain-text-fallback output; carries
+`data-fallback` while showing the plain-text fallback — still-loading peers or a failed render —
+so a consumer can target `lr-markdown [part='content'][data-fallback]` to style it distinctly),
+`heading` (every rendered `<h1>`–`<h6>`, shifted by `heading-offset`), `paragraph` (every rendered
+`<p>`), `list` (every rendered `<ul>`/`<ol>`), `code-block` (every rendered fenced/indented `<pre>`),
+`inline-code` (every rendered inline `<code>` span — backtick spans, not fenced blocks), `link`
+(every rendered `<a>`), `table` (every rendered `<table>`), `blockquote` (every rendered
+`<blockquote>`), `img` (every rendered `<img>`), `math` (a rendered inline or block math span,
+carrying `data-display="inline"|"block"`)
+
+**Themeable custom properties:** `--lr-markdown-font-mono` (default `ui-monospace, SFMono-Regular,
+Menlo, Consolas, monospace` — the code/code-block font; component-specific since no shared
+`--lr-*` monospace token exists), plus shared tokens `--lr-space-xs/-s/-m/-l`,
+`--lr-color-brand-quiet`, `--lr-color-brand`, `--lr-color-border`, `--lr-color-text-quiet`,
+`--lr-radius`.
+
+**Optional peer deps:** `marked`, `dompurify` (both lazy-loaded via `markdown-loader.ts`'s
+`loadMarkdownDeps()`, mirroring `chart-loader.ts`'s two-independent-optional-peers shape). Each half
+is loaded and caught independently — a consumer who installs only `marked` and explicitly sets
+`sanitize="false"` (so `dompurify` is never needed) is a valid, supported combination. Also `shiki`,
+the same optional peer `<lr-code-block>` uses, for `highlightCode`'s fenced-block syntax
+highlighting — independent of the `marked`/`dompurify` pair, and its absence never blocks rendering
+(fenced blocks simply stay unhighlighted).
+
+```html
+<lr-markdown
+  content="# Report&#10;&#10;See the [setup guide](/docs/setup) for details."
+  internal-link-prefix="/docs/"
+></lr-markdown>
+<script>
+  document.querySelector('lr-markdown').addEventListener('lr-link-click', (e) => {
+    router.navigate(e.detail.href);
+  });
+</script>
+```
+
+Rendering never ships unsanitized or broken markup silently. If `marked` fails to load, or throws
+while parsing malformed input, the component falls back to plain text (`white-space: pre-wrap`, no
+HTML parsing at all — the raw `content` string itself) and fires `lr-render-error`. If `sanitize`
+is `true` (the default) and `dompurify` fails to load, the component *also* falls back to plain text
++ `lr-render-error` — it never renders `marked`'s raw HTML output when sanitization was requested
+(or defaulted to) but is unavailable, even though `marked` itself loaded fine. If `sanitize` is
+explicitly `false`, `marked`'s raw output renders as-is regardless of whether `dompurify` is
+installed. While the optional peers are still resolving, the host carries `aria-busy="true"` (set/
+cleared in `updated()` based on whether the deps have loaded) and shows the same plain-text fallback
+rendering — there's no separate loading skeleton, since the un-rendered Markdown source is already
+legible text in the meantime.
+
+**Known gotchas:**
+- a malformed percent-escape or lone UTF-16 surrogate in a link's raw `href` makes the internal
+  `encodeURI`-based validity guard throw, silently dropping just that anchor (the link text still
+  renders, with no `href`) — mirrors `marked`'s own default `link()` renderer's defensive behavior.
+- `target` is not in DOMPurify's default attribute allowlist (unlike `part`/`rel`/`class`, which
+  already are), so sanitization is called with `ADD_ATTR: ['target']` — without that, every rendered
+  link's `target` would be silently stripped by sanitization even though the anchor itself survives.
+- a fresh `marked.Marked()` instance (with a fresh renderer) is built on every single parse rather
+  than cached, specifically so the renderer's `link()` override always closes over the *current*
+  `linkTarget` — `marked`'s `.use()` otherwise persists whatever renderer it was given for the
+  instance's lifetime, which would go stale if `linkTarget` changed after a cached instance's first use.
+- `internal-link-prefix` matching compares against the raw `href` *attribute*, not the resolved
+  `.href` IDL property (always an absolute URL in the browser) — a prefix like `/docs/` matches a
+  relative markdown link but would never match against the resolved property.
+- rendered output goes through `unsafeHTML`; with `sanitize="false"` the component renders whatever
+  HTML `marked` produces from `content` completely unsanitized, so untrusted `content` must never be
+  paired with `sanitize="false"`.
+
+---

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

@@ -0,0 +1,106 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/media.md — do not edit this file. -->
+
+# `lr-media-card`
+
+- **Import** `import '@aceshooting/lyra-ui/components/media/media-card/media-card.js';` (registers the tag; side-effect import)
+- **Class** `LyraMediaCard`, also available unregistered from `@aceshooting/lyra-ui/components/media/media-card/media-card.class.js`
+- **Family** `components/media/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-media-card`
+
+A lightweight inline preview for one already-sent, already-available attachment inside a rendered
+chat message body — distinct from `lr-document-preview` (a fuller viewer with an async
+server-side-conversion state machine) and `lr-attachment-chip` (a pre-send queued-file chip with
+upload progress). This component has neither concern; it only ever shows a `src` that's already
+final.
+
+**Properties:**
+- `src: string = ''` — the media URL. Always re-validated against a safe-scheme allowlist before
+  use (see below) — never trust it unsanitized even though it's typed as a plain string.
+- `kind?: 'image' | 'video' | 'file'` (reflected) — explicit format dispatch. Leave unset to
+  auto-detect from `mimeType`.
+- `mimeType: string = ''` (attribute `mime-type`) — drives auto-detection when `kind` is unset.
+- `filename: string = ''` — shown in the file-chip fallback, used as the download link's suggested
+  filename, and folded into the accessible name.
+- `alt: string = ''` — alt text for the image case (and reused as a video label fallback). Falls
+  back to `filename`, then a generic per-kind description.
+- `accessibleLabel: string = ''` (attribute `aria-label`) — overrides the localized action name on
+  the actual button/link without replacing image alt text or the video control's own label
+- `maxHeight: string = ''` (attribute `max-height`) — a CSS length (e.g. `"16rem"`); once set,
+  overrides the `--lr-media-card-max-height` custom property for this instance only (applied
+  inline on `[part="base"]`, so it reliably wins over a `:host{}`-declared default from outside the
+  shadow root) — same contract as `<lr-document-preview>`'s identically-named prop.
+
+**Events:** `lr-open` (`detail: { src: string; filename: string }`, cancelable) — fired when the
+card (or, for `kind="video"`, its separate `open-button`) is activated. `detail.src` is whichever
+safe-URL sink actually rendered (`safeMediaSrc(src) ?? safeLinkHref(src) ?? src.trim()`), not
+necessarily the raw `src` property verbatim — a whitespace-padded value is trimmed, so `detail.src`
+always matches what the DOM would show if it were safe. This component never navigates on its own
+for `image`/`video` — a host decides what "open" means. The `file`-chip case is the exception: when
+`src` passes the stricter href safety check, the chip is a real `<a href download>` so a bare
+drop-in still does something useful, but `lr-open` fires first — a host calling
+`preventDefault()` on it suppresses that default download/open so it can substitute its own
+handling.
+
+**Slots:** none.
+
+**CSS parts:** `base` (a `<button>` for `kind="image"`, a plain wrapper `<div>` for `kind="video"`,
+an `<a>` or `<span>` for the file-chip fallback depending on href safety), `media` (the `<img>`/
+`<video>`), `file-icon`, `filename` (file-chip fallback only), `open-button` (video only — see
+below).
+
+**Themeable custom properties:** `--lr-media-card-max-height` (default `20rem` — caps `[part="media"]`'s
+block-size so one oversized image/video can't blow out a chat bubble; same naming/contract as
+`<lr-document-preview>`'s identical `--lr-document-preview-max-height`; override per-instance via
+the `max-height` attribute instead of this property directly). Plus shared tokens
+`--lr-space-xs`/`-s`, `--lr-color-border`, `--lr-color-surface`, `--lr-color-text`/`-text-quiet`,
+`--lr-color-brand` (hover border), `--lr-radius`, `--lr-icon-button-size` (video's `open-button`
+sizing), `--lr-focus-ring-*`, `--lr-transition-fast`.
+
+**Optional peer deps:** none.
+
+```html
+<lr-media-card kind="image" src="https://example.com/photo.jpg" alt="Screenshot" filename="photo.jpg"
+  @lr-open=${(e) => openLightbox(e.detail.src)}
+></lr-media-card>
+<lr-media-card kind="file" src="https://example.com/report.pdf" filename="report.pdf"></lr-media-card>
+```
+
+**Safe-URL checking.** `src` is validated (exported as `safeMediaSrc()`/`safeLinkHref()`) before it's
+ever assigned to an `<img>`/`<video>` `src` or an `<a href>` — only `http:`/`https:`/`blob:` (plus
+`data:` for a *media* `src` only) or a scheme-relative/relative URL with no scheme at all pass;
+anything else (`javascript:`, `vbscript:`, and similarly suspicious schemes) is rejected. `data:` is
+allowed for `safeMediaSrc()` (a browser never executes script from a media element's `src`) but
+rejected by the stricter `safeLinkHref()` (a `data:text/html` URI navigated to via a clicked `<a
+href>` runs as a full document and can execute script) — the same scheme gets a different verdict
+depending on which DOM sink it's headed for. Both functions delegate to the platform's own `new
+URL()` parser rather than a hand-rolled scheme regex, specifically because `new URL()` already
+implements the WHATWG URL Standard's input normalization (stripping tab/newline/leading-trailing
+space before looking for a scheme) — a naive regex is vulnerable to exactly the kind of
+tab-injected-into-a-scheme bypass a browser attribute sink still normalizes and executes. An
+`image`/`video` `kind` whose `src` fails the media-src check falls back to the generic file-chip
+rendering, which then separately re-validates `src` against the stricter href allowlist for its own
+download affordance.
+
+`kind="video"` renders its open affordance as a separate `[part="open-button"]` next to
+`[part="media"]` rather than wrapping the whole card in one `<button>`/`<a>` (the pattern
+`image`/`file` use) — a `<video controls>` element is itself interactive content, and HTML forbids
+nesting interactive content inside a `<button>`/`<a>`; doing so anyway would also make every click on
+the video's own native controls bubble up and spuriously fire `lr-open`.
+
+**Known gotchas:**
+- Calling the real `.click()` (or dispatching a `click`/`MouseEvent`) on the file-chip's `<a href>`
+  in a test genuinely triggers real browser navigation — always `preventDefault()` on a `click`
+  listener registered before triggering it, the same precaution `lr-document-preview`'s own
+  download-link tests already take. A synthetic `dispatchEvent(new MouseEvent('click', {cancelable:
+  true}))` still invokes the anchor's native activation behavior if nothing calls
+  `preventDefault()` during dispatch — it is not a safe no-op.
+- `kind` only reflects to the host attribute when explicitly set — CSS keying off the
+  auto-detected resolved kind should target the rendered `[part]`/element (e.g. `video[part="media"]`),
+  not `:host([kind=...])`, since the latter won't see an auto-detected kind.
+
+---

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

@@ -0,0 +1,67 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/retrieval.md — do not edit this file. -->
+
+# `lr-memory-panel`
+
+- **Import** `import '@aceshooting/lyra-ui/components/retrieval/memory-panel/memory-panel.js';` (registers the tag; side-effect import)
+- **Class** `LyraMemoryPanel`, also available unregistered from `@aceshooting/lyra-ui/components/retrieval/memory-panel/memory-panel.class.js`
+- **Family** `components/retrieval/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-memory-panel`
+
+Agent working-memory surface: short-term context and long-term memories, each with confidence and
+optional grounding provenance, and add/remove/forget actions gated behind an explicit confirmation.
+Composes `lr-provenance-panel` (per-item provenance, behind a disclosure toggle) and `lr-confirm-bar`
+(every confirmation).
+
+**Properties:**
+- `shortTerm: LyraMemoryItem[] = []` / `longTerm: LyraMemoryItem[] = []` (both attribute: false) —
+  `LyraMemoryItem { id: string; text: string; confidence?: number; provenance?: LyraProvenance }`
+  (exported here). `text` renders as plain text. `confidence` is 0–1; omit it and the confidence
+  indicator is omitted entirely rather than showing 0%/unknown. `provenance` reuses
+  `lr-provenance-panel`'s own `LyraProvenance` shape verbatim (`{ entities?; relationships?;
+  communities?; chunks? }`); omit it and the disclosure toggle is omitted entirely. Both arrays are
+  controlled and never mutated here — approving an action only fires the matching event
+- `types: NodeTypeStyle[] = []` (attribute: false) — `{ id: string; label: string; color?: string;
+  shape?: 'circle' | 'square' | 'diamond' }`, forwarded verbatim to every expanded item's
+  `lr-provenance-panel`
+- `thresholds: { high: number; medium: number } = { high: 0.75, medium: 0.5 }` (attribute: false) —
+  confidence-tier boundaries (reusing `lr-citation-badge`'s high/medium/low confidence vocabulary and
+  success/warning/danger tones), also forwarded as the provenance relevance tiers
+- `label: string = ''` — overall accessible label override
+
+**Events:**
+- `lr-add` (`detail: LyraMemoryAddDetail` = `{ item: LyraMemoryItem }`) — a pending "promote to
+  long-term" was approved; the short-term item as-is. Only offered on short-term items.
+- `lr-remove` (`detail: LyraMemoryRemoveDetail` = `{ id: string; scope: 'short-term' | 'long-term' }`)
+  — a pending per-item removal was approved. Offered on every item.
+- `lr-forget` (`detail: undefined`) — the pending "forget all long-term memories" bulk action was
+  approved. Only rendered while `longTerm` is non-empty.
+- `lr-expand` (`detail: LyraMemoryExpandDetail` = `{ id: string; expanded: boolean }`) — an item's
+  provenance disclosure was toggled.
+
+**Slots:** none.
+
+**CSS parts:** `base`, `empty` (the all-empty `lr-empty`, shown when both lists are empty),
+`section` (one of the two, carries `data-scope`), `section-header`, `heading` (a section's visible
+heading text), `section-empty`, `list` (`role="list"`, omitted while that section is empty), `item`
+(`role="listitem"`, carries `data-id`/`data-scope` and a stable `tabindex="-1"` so focus has
+somewhere to land after a confirmation resolves), `item-row`, `item-text`, `confidence` (carries
+`data-tone`; omitted when `confidence` is unset), `expand-toggle` / `item-body` (both omitted when
+`provenance` is unset; `item-body` is `hidden` while collapsed), `item-actions`, `add-button`,
+`remove-button`, `forget-all-button`.
+
+**Themeable custom properties:** shared tokens only.
+
+**Optional peer deps:** none.
+
+**Known gotchas:**
+- At most one confirmation is pending at a time — starting a new action (same item or not) silently
+  cancels whichever confirmation was already open.
+- `remove` (one item, either list) and `forget` (the whole long-term list) are deliberately distinct
+  actions; there is no per-item forget and no bulk remove.
+
+---

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

@@ -0,0 +1,139 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/utility.md — do not edit this file. -->
+
+# `lr-mention-popover`
+
+- **Import** `import '@aceshooting/lyra-ui/components/utility/mention-popover/mention-popover.js';` (registers the tag; side-effect import)
+- **Class** `LyraMentionPopover`, also available unregistered from `@aceshooting/lyra-ui/components/utility/mention-popover/mention-popover.class.js`
+- **Family** `components/utility/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-mention-popover`
+
+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.
+
+**Properties:**
+- `anchor?: HTMLElement` (attribute: false) — the element to position the popup relative to. A
+  plain `<textarea>` or single-line text `<input type="text"|"search">` gets caret-precise
+  positioning; any other element anchors the whole popup under that element's own box.
+- `items: MentionItem[] = []` (attribute: false) — the full candidate set, pre-`query`-filtering.
+- `query: string = ''` — the text typed since the trigger character; drives the built-in filtering
+  (see `filter`).
+- `open: boolean = false` (reflected)
+- `filter: MentionFilter | null = null` (attribute: false) — overrides the built-in
+  case-insensitive `label`/`description` substring match entirely.
+- `emptyText: string = 'No matches'` (attribute `empty-text`)
+- `label: string = 'Suggestions'` — accessible name for the `role="listbox"` popup. A host-level
+  plain `aria-label` attribute on `<lr-mention-popover>` itself takes priority over this property
+  when present (checked via a plain `getAttribute()` read, not a reactive property) — matches the
+  same fallback on `<lr-combobox>`/`<lr-table>`.
+- `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).
+
+**Exported types:** `MentionItem { id: string; label: string; description?: string; icon?: string
+}`; `MentionFilter = (item: MentionItem, query: string) => boolean`; `MentionSelectDetail { id:
+string; label: string }`.
+
+**Events:** `lr-mention-select` (`detail: MentionSelectDetail`, `{ id, label }` of the row that
+was committed via Enter/Tab/click), `lr-mention-close` (no detail payload —
+`this.emit('lr-mention-close')` is called with no second argument, so `event.detail` is `null`,
+not `undefined`; fires on Escape or any other `open: true -> false` transition, but never for the
+close that immediately follows a `lr-mention-select` commit, and never for markup that simply
+renders `open="false"` on first paint)
+
+**Slots:** none.
+
+**CSS parts:** `listbox`, `option`, `option-icon` (when `icon` is set), `option-label`,
+`option-description` (when `description` is set), `empty`
+
+**Themeable custom properties:** shared tokens only — `--lr-space-xs`/`-s`/`-m` (popup padding,
+row padding/gap), `--lr-color-surface`/`-border` (popup background/border), `--lr-radius`
+(popup and row corners), `--lr-shadow` (popup elevation), `--lr-transition-fast` (open/close
+transition), `--lr-color-brand-quiet` (active-row background), `--lr-color-brand` (selected-row
+text), `--lr-color-text-quiet`/`--lr-color-text` (description text, full-contrast on the active
+row).
+
+**Optional peer deps:** none.
+
+```html
+<textarea id="composer"></textarea>
+<lr-mention-popover id="mentions" label="People" empty-text="No matches"></lr-mention-popover>
+<script type="module">
+  const textarea = document.getElementById('composer');
+  const popover = document.getElementById('mentions');
+
+  textarea.addEventListener('keydown', (e) => {
+    if (popover.open && popover.handleKeyDown(e)) return; // consumed
+  });
+  textarea.addEventListener('input', () => {
+    popover.anchor = textarea;
+    popover.items = [
+      { id: 'ada', label: 'Ada Lovelace', description: 'Engineering', icon: '👩‍💻' },
+      { id: 'grace', label: 'Grace Hopper', description: 'Engineering' },
+    ];
+    popover.query = 'a'; // detected since the trigger character
+    popover.open = true;
+  });
+
+  popover.addEventListener('lr-mention-select', (e) => {
+    // splice `${e.detail.label}` into the textarea at the trigger offset
+  });
+</script>
+```
+
+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.
+
+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
+`place()`, so the popup tracks the caret rather than sitting under the whole textarea. Re-measures
+automatically only on an `anchor` or `query` change while open (a keystroke moves the caret, so a
+fresh `query` is the proxy for "the caret may have moved").
+
+**Known gotchas:**
+- 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>`.
+- 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.
+- Caret-precise positioning only applies to a plain `<textarea>` or single-line text
+  `<input type="text"|"search">`; any other `anchor` element, or a text control whose caret rect
+  can't be measured (e.g. `display: none`), silently falls back to whole-element anchoring against
+  `anchor` itself.
+- A caret that moves for a reason other than typing (e.g. a mouse click elsewhere in the text while
+  the popover happens to still be open) is not separately tracked — force a re-measure by toggling
+  `open` or reassigning `anchor`.
+- `activeIndex` resets to `0` whenever `query` or `items` changes, but not when only `anchor`
+  changes — reassigning `anchor` alone preserves whatever row was last highlighted.
+- There's no persisted "selection" the way `<lr-combobox>`'s own listbox has one — a mention is
+  either committed (closing the popover) or dismissed with nothing chosen. `aria-selected="true"`
+  here marks whichever row is currently *active* (what Enter/Tab would commit right now, per the
+  WAI-ARIA combobox-with-list-autocomplete pattern), not a separate persisted value.
+
+---