@aceshooting/lyra-ui 5.0.0 → 5.1.0

package/llms/components/lr-code-editor.md

@@ -0,0 +1,72 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/forms.md — do not edit this file. -->
+
+# `lr-code-editor`
+
+- **Import** `import '@aceshooting/lyra-ui/components/forms/code-editor/code-editor.js';` (registers the tag; side-effect import)
+- **Class** `LyraCodeEditor`, also available unregistered from `@aceshooting/lyra-ui/components/forms/code-editor/code-editor.class.js`
+- **Family** `components/forms/` — 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-code-editor`
+
+Dependency-free, form-associated multiline code editor built around a native textarea, with an
+optional line-number gutter. No syntax highlighting: `language` is metadata only.
+
+**Properties:**
+- `language: string = ''` — reflected onto the `editor` part as `data-language`; purely a styling/
+  metadata hook, nothing tokenizes the text
+- `lineNumbers: boolean = true` (attribute `line-numbers`, reflected) — renders the `gutter` part,
+  one row per `\n`-separated line
+- `tabSize: number = 2` (attribute `tab-size`) — spaces inserted per Tab press, and the textarea's
+  inline `tab-size`. Sanitized on assignment to a finite integer clamped to `1..16`, so a
+  `NaN`/`Infinity` value can neither empty the insert nor throw out of `String.repeat()`
+- `label: string = ''`, `hint: string = ''`, `errorText: string = ''` (attribute `error-text`),
+  `placeholder: string = ''`
+- `readonly: boolean = false` (reflected) — also disables Tab indentation
+- `resize: 'none' | 'both' | 'horizontal' | 'vertical' = 'both'` — written as the textarea's inline
+  `resize`
+- `wrap: 'off' | 'soft' | 'hard' = 'off'` — native textarea wrapping; `'off'` (the default) makes
+  the `editor` part the single horizontal scroll viewport
+- `spellcheck: boolean = false` — off by default for code, and parsed with a string-aware converter
+  so `spellcheck="false"` really is `false`
+- `autocapitalize: string = 'off'`, `autoCorrect: string = 'off'` (attribute `autocorrect`)
+- `accessibleLabel: string = ''` (attribute `aria-label`) — wins over `label`/the localized
+  `codeEditorLabel` fallback on the internal textarea
+
+**Methods:** `focus(options?)`, `blur()`, `select()`, `setSelectionRange(start, end, direction?)`,
+`setRangeText(replacement, start?, end?, selectMode?)` (writes the result back into `value` without
+emitting an event), plus the `selectionStart`/`selectionEnd` getters (both `0` before first render).
+
+**Events:** `input` and `change` — Lyra-emitted, bubbling/composed, each with `detail: { value }`
+(so they carry a detail a native `input`/`change` would not); also `focus`/`blur`, re-dispatched
+bubbling and composed from the internal textarea.
+
+**Slots:** `label`, `hint`, `error`.
+
+**CSS parts:** `form-control`, `label` (**not** `form-control-label` as on the other form
+components), `editor` (the bordered frame and the single scroll viewport), `gutter` (line numbers,
+`aria-hidden`, only when `lineNumbers`), `textarea`, `hint`, `error`.
+
+**Themeable custom properties:** `--lr-code-editor-min-block-size` (default `--lr-size-8rem`, the
+frame's and textarea's height floor) and `--lr-code-editor-line-height` (default `1.5`, applied to
+both gutter and textarea so line numbers stay aligned with their lines).
+`--lr-code-editor-tab-size` (default `2`) is read by the `textarea` part's rule and drives both the
+rendered tab stops and the number of spaces Tab inserts. Precedence, highest first: an explicitly
+assigned `tabSize` (property or `tab-size` attribute) > a host-level `--lr-code-editor-tab-size` >
+the `:host` default of `2`. The component writes the token inline on the `textarea` part only while
+`tabSize` has been assigned, so an untouched `tabSize` leaves your override in charge; removing the
+`tab-size` attribute hands control back to the token. A length-valued override (`40px`, `2ch`, …)
+still sets the visual tab stops for literal tab characters, but is not reinterpreted as a count of
+spaces — the Tab key keeps inserting `tabSize` spaces in that case.
+
+**Known gotchas:**
+- Keyboard contract (no keyboard trap, WCAG 2.1.2): Tab inserts one indent unit of spaces at the
+  caret (see the tab-width precedence above);
+  Shift+Tab is never captured, so reverse focus traversal always works; pressing Escape releases
+  the *next* Tab for forward traversal instead, and any other keypress (or focus leaving the
+  editor) re-arms Tab indentation.
+- The host gets a `data-invalid` attribute once the field has been blurred at least once and
+  validity fails; the styles hang the danger border off it.

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

@@ -0,0 +1,21 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/forms.md — do not edit this file. -->
+
+# `lr-color-picker`
+
+- **Import** `import '@aceshooting/lyra-ui/components/forms/color-picker/color-picker.js';` (registers the tag; side-effect import)
+- **Class** `LyraColorPicker`, also available unregistered from `@aceshooting/lyra-ui/components/forms/color-picker/color-picker.class.js`
+- **Family** `components/forms/` — 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-color-picker`
+
+A form-associated native color picker with label, hint, and error chrome. **Properties:** the shared
+form properties `name`, `value`, `disabled`, and `required`, plus `label`, `hint`, `errorText`
+(`error-text`), and `accessibleLabel` (`aria-label`). **Slots:** `label`, `hint`, `error`. **Events:**
+composed `input` and `change`, `lr-change` with `{ value }`, and `focus`/`blur` (re-dispatched from
+the internal `<input>`'s own `focus`/`blur`, bubbling and composed unlike the native events). **CSS
+parts:** `form-control`, `form-control-label` (the label; `label` is an alias kept for back-compat),
+`input`, `hint`, `error`.

package/llms/components/lr-combobox.md

@@ -0,0 +1,196 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/forms.md — do not edit this file. -->
+
+# `lr-combobox`
+
+- **Import** `import '@aceshooting/lyra-ui/components/forms/combobox/combobox.js';` (registers the tag; side-effect import)
+- **Class** `LyraCombobox`, also available unregistered from `@aceshooting/lyra-ui/components/forms/combobox/combobox.class.js`
+- **Family** `components/forms/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Documented with** `lr-option` (same section below)
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-combobox` / `lr-option`
+
+Filterable single/multi-select combining a text input with a listbox. Mirrors the core
+`<wa-combobox>` API under the `lr-` prefix. **Form-associated** (hand-rolled internals, not the
+shared `FormAssociated` mixin — see gotchas).
+
+### `lr-combobox`
+
+**Properties:**
+- `multiple: boolean = false` (reflected)
+- `size: 'xs' | 's' | 'm' | 'l' | 'xl' = 'm'` (reflected — same scale as `lr-select`'s `size`;
+  also scales the "+N" overflow tag and decorative expand icon; `size="s"` shares its outer
+  control height with `lr-input`, `lr-select`, and `lr-segmented` without part overrides)
+- `placeholder: string = ''`
+- `disabled: boolean = false` (reflected)
+- `required: boolean = false` (reflected — enforced via `internals.setValidity()`; also reflected as
+  `aria-required` on `<input part="combobox-input">` immediately, and `aria-invalid` once the field
+  has been touched, see gotchas)
+- `name: string = ''`
+- `label: string = ''`
+- `hint: string = ''`
+- `errorText: string = ''` (attribute `error-text` — static error copy shown below the hint;
+  overridden by slotted `error` content when provided)
+- `open: boolean = false` (reflected)
+- `clearable: boolean = false` (reflected) — displays the clear button while a value is selected
+- `withClear: boolean = false` (attribute `with-clear`) — deprecated compatibility alias for
+  `clearable`; either property enables the same clear button
+- `autocomplete: string = 'off'`, `inputMode: string = ''` (attribute `inputmode`),
+  `enterKeyHint: string = ''` (attribute `enterkeyhint`), `spellcheck: boolean = true`,
+  `autocapitalize: string = ''`, and `autoCorrect: string = ''` (attribute `autocorrect`) — native
+  editing-assistance attributes forwarded to the internal filter input
+- `maxOptionsVisible: number = 3` (attribute `max-options-visible` — caps how many selected tags
+  show before collapsing to `+N`)
+- `emptyText: string = 'No results'` (attribute `empty-text`)
+- `loadingText: string = 'Loading…'` (attribute `loading-text` — listbox row shown while a `source`
+  fetch is in flight)
+- `overflowText: string = '+{n} more — refine your search'` (attribute `overflow-text` — listbox row
+  shown when `maxRender` caps the row list; `{n}` is replaced with the hidden count)
+- `filter: OptionFilter | null = null` (attribute: false — `(option, query) => boolean`; default
+  matches `label`/`searchText` case-insensitively; ignored while `source` is set)
+- `source: ComboboxSource | null = null` (attribute: false — `(query: string) =>
+  Promise<ComboboxSourceRow[]>`; when set, replaces the light-DOM `<lr-option>` list with an async
+  lookup, debounced ~200ms after each keystroke and re-run on clear/pick. `loadingText` is shown
+  while a call is in flight; a stale in-flight call that resolves after a newer one (or after
+  disconnect) is dropped via a monotonic token)
+- `maxRender: number = 200` (attribute `max-render` — caps how many rows render at once, always
+  keeping the current selection visible even if it's outside the cap; the excess renders as one
+  `overflowText` row instead of being dropped silently)
+- `value: string | string[]` — a getter/setter: plain `string` in single mode, `string[]` in
+  `multiple` mode
+- `selectedRows: ComboboxSourceRow[]` (read-only getter) — structured rows for the current
+  selection, including any opaque `data` payload supplied by an async source. Selected async rows
+  remain available after the query changes or a later source result no longer contains them
+- `selectionStart`, `selectionEnd`, and `selectionDirection` — selection getters/setters forwarded
+  to the internal input
+
+**Methods:** `focus(options?)`, `blur()`, `select()`, `setSelectionRange()`, and `setRangeText()`
+forward to the internal input. `setRangeText()` synchronizes the filter query and visible options.
+
+`ComboboxSourceRow = { value: string; label: string; sub?: string; icon?: unknown; badge?: string |
+number; accessibleLabel?: string; data?: unknown; dotColor?: string; group?: string; disabled?:
+boolean }` — the row shape used by the async `source` path. `icon` renders as a decorative leading
+visual, `badge` as trailing metadata, `accessibleLabel` can provide richer spoken text than the
+visible label, and `data` is retained without being rendered for retrieval through `selectedRows`.
+The light-DOM `<lr-option>` path normalizes its supported label/sub/dot/group fields to the same
+internal row model.
+
+**Events:** typing in the filter exposes the original bubbling/composed, non-cancelable `InputEvent`
+as exactly one host `input` event and does not fire `change`. An actual user selection mutation —
+pointer or keyboard selection, multiple-value toggle, tag/Backspace removal, or clear — emits exactly
+one bubbling/composed, non-cancelable plain `input` `Event`, immediately followed by the same shape
+of `change` `Event`. Re-picking the current single value and programmatic/default/reset/restore
+writes are silent. The clear button emits one `lr-clear` after its `input`/`change` pair.
+`lr-filter` (`detail: { value: string }`) reports the in-progress filter text on every user-driven
+keystroke — the live as-you-typed search string, deliberately *not* `value`, which is the committed
+selection. It is the supported way to read that text; reaching into the shadow root for
+`[part="combobox-input"]`'s value is not. Named `lr-filter` rather than `lr-input` precisely because
+`lr-input`'s detail on `<lr-input>` is the committed value, and the two must not share a name while
+carrying different strings. It fires for user input only: picking a row, the clear button,
+`form.reset()`, dismissing the listbox, a programmatic `value` write, and `setRangeText()` all blank
+the filter silently, mirroring how `<lr-input>`'s `lr-input` only reports user edits.
+
+`lr-show` and `lr-hide` report listbox visibility transitions.
+The internal input's `focus` and `blur` are re-dispatched as bubbling, composed host events.
+
+**Slots:** default (`<lr-option>` children), `label`, `hint`, `error` (overrides the `errorText`
+attribute when provided)
+
+**CSS parts:** `form-control`, `form-control-label`, `combobox`, `tags`, `tag`,
+`tag__remove-button`, `combobox-input`, `clear-button`, `expand-icon`, `listbox`, `option`,
+`option-dot` (the leading status dot, when a row's `dotColor` is set), `option-icon` (the decorative
+leading visual for an async row), `option-label`, `option-sub` (a row's secondary line, when `sub`
+is set), `option-badge` (an async row's trailing metadata), `option-overflow` (the "+N more"
+indicator from `maxRender`), `error`, `hint`
+
+**Themeable custom properties:** `--lr-combobox-trigger-padding`,
+`--lr-combobox-trigger-min-height`, `--lr-combobox-font-size`, `--lr-combobox-tag-padding`,
+`--lr-combobox-tag-font-size`, and `--lr-combobox-expand-size` (the decorative icon box; each
+standard size supplies an aligned default), plus shared tokens.
+
+**Optional peer deps:** none.
+
+### `lr-option`
+
+**Properties:**
+- `value: string = ''`
+- `disabled: boolean = false`
+- `selected: boolean = false` (reflected — set by the parent combobox, but also **read** on initial
+  mount, see below)
+- `group: string = ''` (section header)
+- `searchText: string = ''` (attribute `search-text` — extra text the filter matches beyond the
+  visible label)
+- `sub: string = ''` (optional secondary line rendered under the label, e.g. a status/date summary)
+- `dotColor: string = ''` (attribute `dot-color` — optional CSS color for a small leading status
+  dot, any valid CSS color)
+- `label` is a **read-only getter**: explicit `label` attribute wins, else trimmed `textContent`.
+
+```html
+<lr-combobox id="cb" label="Country" placeholder="Search…" with-clear>
+  <lr-option value="fr">France</lr-option>
+  <lr-option value="de" search-text="deutschland">Germany</lr-option>
+</lr-combobox>
+<script type="module">
+  document.getElementById('cb').addEventListener('change', (e) => console.log(e.target.value));
+</script>
+```
+
+```html
+<!-- Async data source instead of light-DOM <lr-option> children: -->
+<lr-combobox id="cb2" label="Fruit (async)" with-clear></lr-combobox>
+<script type="module">
+  document.getElementById('cb2').source = async (query) => {
+    const rows = await fetchFruit(query); // your own lookup
+    return rows.map((r) => ({
+      value: r.id,
+      label: r.name,
+      icon: renderFruitIcon(r),       // decorative; hidden from assistive technology
+      badge: r.category,
+      accessibleLabel: `${r.name}, ${r.category}`,
+      data: r,                        // retained in cb2.selectedRows after selection
+    }));
+  };
+</script>
+```
+
+Multi-select submits as **repeated `FormData` entries** (not a joined string) —
+`new FormData(form).getAll(name)` behaves like a native multi-value control. An unnamed multi-select
+(`multiple` with no `name`) contributes nothing to the form at all, matching a nameless native
+`<select multiple>`, rather than falling back to a shared literal key that could collide with
+another unnamed combobox in the same form.
+Session-history/autofill state is stored as a name-independent JSON string array. A valid string
+array restores the selection (single mode keeps its first entry); malformed or wrong-shape state
+restores an empty selection. Restored state wins even when it arrives before the first option
+collection, while `form.reset()` still returns to the declarative selected default. Restoration is
+synchronous and fires no `input`/`change` event.
+
+**Known gotchas:**
+- `with-clear` remains supported for compatibility, but new code should use the mirrored
+  `clearable` property/attribute.
+- a host-level `aria-label` attribute on `<lr-combobox>` now takes priority over `label`/
+  `placeholder`/`"Combobox"` when resolving the accessible name on `[part="combobox-input"]` —
+  previously it was silently ignored. Matches the same fallback on `<lr-select>`.
+- `aria-required` reflects `required` immediately; `aria-invalid`, by contrast, only reflects
+  **after the field has been touched** (first `blur`) — a `required` field with a validity error
+  doesn't look invalid to assistive tech before that, by design (avoids flashing invalid styling on
+  first render). Blurring the input (Tab away) now also closes an open listbox, the same as a
+  native `<select>`'s popup, not just a click outside or Escape.
+- `dotColor`/`sub`/`group` are read from light-DOM `<lr-option>` children as before, but are also
+  first-class fields on `ComboboxSourceRow` for the async `source` path — an async lookup can drive
+  the same grouped/dot/sub-text rendering a static option list can.
+- `icon`, `badge`, `accessibleLabel`, and `data` are async-source row features rather than
+  `<lr-option>` properties. Icons are decorative (`aria-hidden`); use `accessibleLabel` when the
+  visible label/sub/badge combination needs a fuller spoken name. `data` is deliberately opaque and
+  is available only through the read-only `selectedRows` getter.
+- Full ARIA 1.2 combobox pattern (`role=combobox`, roving `aria-activedescendant`, real DOM focus
+  kept on the input) is implemented correctly — a genuine strength, safe to build on. Declaratively-
+  selected options (`<lr-option value="b" selected>`) are seeded into the selection (mirroring
+  native `<select><option selected>`) both the first time options are collected **and** for any
+  later batch slotted in afterward (e.g. a lazily-populated list appended post-connect) — only the
+  `form.reset()` default itself is captured exclusively from that very first pass; a later pick, or
+  a later batch of newly-`selected` options, never redefines what a reset restores to.
+
+---

package/llms/components/lr-command-palette.md

@@ -0,0 +1,50 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/layout.md — do not edit this file. -->
+
+# `lr-command-palette`
+
+- **Import** `import '@aceshooting/lyra-ui/components/layout/command-palette/command-palette.js';` (registers the tag; side-effect import)
+- **Class** `LyraCommandPalette`, also available unregistered from `@aceshooting/lyra-ui/components/layout/command-palette/command-palette.class.js`
+- **Family** `components/layout/` — 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-command-palette`
+
+Searchable application command menu. Renders nothing at all while closed. Uses the same shared
+overlay infrastructure as `lr-dialog` (focus-trapping Tab, Escape dismissal, backdrop-click
+dismissal, ref-counted document scroll lock).
+
+**Properties:**
+- `open: boolean = false` (reflected)
+- `commands: LyraCommand[] = []` (attribute: false) — `{ id, label, description?, group?, shortcut?,
+  keywords?, disabled?, onSelect? }`. Filtering is case-insensitive substring matching over
+  `label` + `description` + `group` + `keywords` joined together (not fuzzy/subsequence), memoized
+  per `commands` array identity — reassign the array, never mutate it in place. Consecutive commands
+  sharing a `group` render one `[part='group']` heading, so pre-sort by group yourself.
+- `shortcut: string = 'mod+k'` — global toggle chord parsed as `+`-separated parts; `mod` resolves to
+  Cmd on Mac and Ctrl elsewhere. The listener is on `window`, added in `connectedCallback`.
+- `accessibleLabel: string = ''` (attribute `aria-label`) — overrides the localized dialog name
+
+**Methods:** `openPalette()` (clears the query and resets the active row; no-op if already open),
+`close()`, `registerCommand(command)` — appends to `commands` and returns an unregister function.
+
+**Keyboard:** ArrowUp/ArrowDown move the active option, skipping `disabled` rows and clamping (not
+cycling) at the ends; the active row is scrolled into view. Enter selects. Hovering a non-disabled
+row also makes it active.
+
+**Events:** `lr-open`, `lr-close` (both `detail: undefined`), `lr-select` (`detail: { command }`,
+fired before the command's own `onSelect` runs and before the palette closes).
+
+**Slots:** none.
+
+**CSS parts:** `backdrop`, `dialog` (the `role="dialog" aria-modal="true"` panel), `search` (the
+input row), `input` (the `type="search"` field), `list` (the `role="listbox"`), `group` (a group
+heading), `command` (a `role="option"` button), `description`, `shortcut`, `empty`.
+
+**Themeable custom properties:** `--lr-command-palette-z-index` (default
+`var(--lr-overlay-stack-index, var(--lr-layer-modal))`), `--lr-command-palette-offset-block-start`
+(default `12vh` — how far down the viewport the dialog sits), `--lr-command-palette-max-inline-size`
+(default `var(--lr-size-48rem)`), `--lr-command-palette-max-block-size` (default `70vh`), and
+`--lr-command-palette-list-max-block-size` (default `50vh` — the scrolling result list).

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

@@ -0,0 +1,33 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/agent-tools.md — do not edit this file. -->
+
+# `lr-commit-card`
+
+- **Import** `import '@aceshooting/lyra-ui/components/agent-tools/commit-card/commit-card.js';` (registers the tag; side-effect import)
+- **Class** `LyraCommitCard`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/commit-card/commit-card.class.js`
+- **Family** `components/agent-tools/` — 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-commit-card`
+
+A compact commit summary (subject, author/time, diffstat, per-file changes) that links file rows out
+to a diff view.
+
+**Properties:** `hash: string = ''`, `message: string = ''`, `author: string = ''`, `timestamp?:
+number` (attribute: false, epoch milliseconds), `files: CommitFileChange[] = []` (attribute: false) —
+`CommitFileChange { path: string; additions: number; deletions: number; status?: GitStatus }`
+(exported here), where `GitStatus = 'added' | 'modified' | 'deleted' | 'renamed' | 'untracked' |
+'conflicted' | 'ignored'` (shared with `lr-file-tree`); the diffstat is summed from `additions`/
+`deletions` across `files`. `filesCollapsed:
+boolean = true` (attribute `files-collapsed`, reflected), and `copyable: boolean = true` (reflected).
+
+**Slots:** `actions` — trailing header controls (e.g. an "open PR" button).
+
+**Events:** `lr-file-select` (`detail: { path: string }`), `lr-toggle` (`detail: { collapsed: boolean
+}`), and `lr-copy` (`detail: { text: string }`, the full hash was copied).
+
+**CSS parts:** `base`, `subject`, `body`, `hash`, `meta`, `author`, `time`, `diffstat`, `additions`,
+`deletions`, `files-toggle`, `file` (carries `data-status`), `file-path`, `file-additions`,
+`file-deletions`, `copy-button`, and `actions`.

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

@@ -0,0 +1,54 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/retrieval.md — do not edit this file. -->
+
+# `lr-community-card`
+
+- **Import** `import '@aceshooting/lyra-ui/components/retrieval/community-card/community-card.js';` (registers the tag; side-effect import)
+- **Class** `LyraCommunityCard`, also available unregistered from `@aceshooting/lyra-ui/components/retrieval/community-card/community-card.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-community-card`
+
+A cluster/community summary card (GraphRAG community report): label, LLM summary excerpt, member
+count, member chips with overflow, and a drill-in action. Doesn't own community rendering on the
+graph or membership fetching — `lr-drill` asks the host to load members/subgraph.
+
+**Properties:**
+- `community: LyraCommunity | null = null` (attribute: false) — `LyraCommunity { id: string; label:
+  string; summary?: string; memberCount?: number }`; `memberCount` is authoritative when it exceeds
+  `members.length`; `null` renders the empty state
+- `members: LyraEntity[] = []` (attribute: false) — rendered as chips, up to `maxMembers`
+- `maxMembers: number = 8` (attribute `max-members`) — remaining members collapse into a "+N"
+  overflow chip
+- `compact: boolean = false` (reflected) — omits the summary excerpt and member chips
+
+**Events:** `lr-drill` (`detail: { id }`, the drill button, header, or overflow chip — all three
+mean "show me this whole community"), `lr-entity-activate` (`detail: { id }`, a member chip was
+activated).
+
+**Slots:** `actions` — extra header actions alongside the built-in drill button.
+
+**CSS parts:** `base`, `header`, `title` (`role="heading" aria-level="3"` wrapping a `<button>`),
+`member-count`, `summary` (omitted in `compact`), `members` (omitted in `compact`), `member`,
+`overflow` (the "+N" chip button), `drill-button`, `actions`, `empty` (shown when `community` is
+`null`).
+
+**Themeable custom properties:** shared tokens only.
+
+**Optional peer deps:** none.
+
+```html
+<lr-community-card></lr-community-card>
+<script>
+  document.querySelector('lr-community-card').community = { id: 'c1', label: 'Early computing pioneers', summary: 'A cluster of 19th-century mathematicians and engineers.', memberCount: 12 };
+</script>
+```
+
+**Known gotchas:**
+- `memberCount` (not `members.length`) is the authoritative displayed count whenever it's larger —
+  useful when the host sends only a preview slice of members alongside the real total.
+
+---

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

@@ -0,0 +1,38 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/agent-tools.md — do not edit this file. -->
+
+# `lr-compare-panel`
+
+- **Import** `import '@aceshooting/lyra-ui/components/agent-tools/compare-panel/compare-panel.js';` (registers the tag; side-effect import)
+- **Class** `LyraComparePanel`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/compare-panel/compare-panel.class.js`
+- **Family** `components/agent-tools/` — 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-compare-panel`
+
+Side-by-side A/B output comparison with a winner vote (LMSYS-arena / LangSmith-pairwise style): two
+slotted panes, a vote bar, synchronized reading.
+
+**Properties:** `labelA: string = ''` (attribute `label-a`) and `labelB: string = ''` (attribute
+`label-b`) — pane headings. `vote: 'a' | 'b' | 'tie' | 'both-bad' | null = null` (reflected) — the
+recorded winner, host-writable to reflect a previously-recorded vote back. `itemId: string = ''`
+(attribute `item-id`) — an opaque id round-tripped through `lr-vote`. `hideTie: boolean = false`
+(attribute `hide-tie`) and `hideBothBad: boolean = false` (attribute `hide-both-bad`) hide the
+corresponding vote button. `syncScroll: boolean = false` (attribute `sync-scroll`) links both panes'
+scroll position.
+
+**Slots:** `a` (the first output — any content, a chat message, markdown, a viewer), `b` (the second
+output), and `prompt` (optional shared-input header above both panes).
+
+**Events:** `lr-vote` — `detail: { choice: 'a' | 'b' | 'tie' | 'both-bad'; itemId: string }`.
+
+**CSS parts:** `base` (the outer wrapper), `prompt` (the optional prompt header, hidden when the
+`prompt` slot is empty), `panes` (the row, or under 640px column, wrapping both panes), `pane-a`,
+`pane-b` (each pane's labeled scroll region), `pane-header` (a pane's visible heading), `vote-bar`
+(the `role="group"` row of vote buttons), `vote-button` (one vote button), and `live-region` (the
+internal vote-announcement live region).
+
+**Themeable custom properties:** `--lr-compare-panel-max-height` (default `var(--lr-size-24rem)`) —
+cap on each pane's scroll region before it scrolls internally.

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

@@ -0,0 +1,48 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/agent-tools.md — do not edit this file. -->
+
+# `lr-confirm-bar`
+
+- **Import** `import '@aceshooting/lyra-ui/components/agent-tools/confirm-bar/confirm-bar.js';` (registers the tag; side-effect import)
+- **Class** `LyraConfirmBar`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/confirm-bar/confirm-bar.class.js`
+- **Family** `components/agent-tools/` — 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-confirm-bar`
+
+An inline, non-modal approve/deny block for one proposed action — the in-flow sibling of
+`lr-tool-approval-dialog` for confirmations that should sit in the transcript instead of hijacking
+focus. Same `lr-approve`/`lr-deny` event shapes as the dialog, and the same
+`toolApprovalHeading`/`toolApprovalArgsLabel`/`deny`/`approve` localization keys, so the two always
+translate in lockstep. Non-modal by contract: no focus trap, no scroll lock, no Escape/backdrop
+semantics, and it never steals focus when it appears in the transcript. DOM and tab order put Deny
+before Approve. On activation, focus moves synchronously to `[part="status"]` (an always-rendered,
+`tabindex="-1"` element) before the Deny/Approve buttons unmount.
+
+**Properties:** `toolName: string = ''` (attribute `tool-name`) — drives the default heading through
+the existing `toolApprovalHeading`/`toolApprovalGenericTool` dialog keys. `heading: string = ''` —
+free-form heading override for non-tool proposals; wins over `toolName`. `args: unknown = undefined`
+(attribute: false) — shown read-only inside a collapsed `lr-details` + `lr-json-viewer` when
+defined. `decision: 'approved' | 'denied' | null = null` (reflected) — decided state, set by the
+component on activation and host-writable (an externally-resolved decision renders identically but
+emits nothing). `tone: 'neutral' | 'danger' = 'neutral'` (reflected).
+
+**Slots:** default — supplementary body content between the heading and the actions (e.g. a
+`lr-diff-view`). `footer` — extra content at the start of the action row.
+
+**Events:** `lr-approve` (`detail: { args }` — the `args` prop as-is, identical shape to
+`lr-tool-approval-dialog`), `lr-deny` (no detail, identical to the dialog).
+
+**CSS parts:** `base` (`role="group"`), `heading`/`tool-name`, `body`, `args` (the
+details/json-viewer wrapper, only rendered when `args` is defined), `footer`, `deny-button`,
+`approve-button` (named identically to the dialog's parts), `status` (the decided-state text, always
+present in the DOM as a focus landing spot).
+
+```html
+<lr-tool-call-chip status="pending"></lr-tool-call-chip>
+<lr-confirm-bar tool-name="run_shell" .args=${args}
+  @lr-approve=${(e) => run(e.detail.args)} @lr-deny=${() => cancel()}
+></lr-confirm-bar>
+```

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

@@ -0,0 +1,34 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/viewers.md — do not edit this file. -->
+
+# `lr-contact-viewer`
+
+- **Import** `import '@aceshooting/lyra-ui/components/viewers/contact-viewer/contact-viewer.js';` (registers the tag; side-effect import)
+- **Class** `LyraContactViewer`, also available unregistered from `@aceshooting/lyra-ui/components/viewers/contact-viewer/contact-viewer.class.js`
+- **Family** `components/viewers/` — 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-contact-viewer`
+
+Fetches a vCard document and renders one accessible card per contact. The document registry matches
+`.vcf` filenames and the `FN`, `ORG`, `TEL`, `EMAIL`, and `ADR` fields are displayed. `N` is parsed
+but never rendered — the card's heading uses `FN` (falling back to a localized "unnamed contact"
+label when `FN` is absent).
+
+Remote resources are capped at 25 MB; exceeding it surfaces the localized
+`documentPreviewResourceTooLarge` message instead of the contacts.
+
+**Properties:** `src`, `name`, and `maxHeight` (attribute `max-height`) are strings.
+
+**Events:** `lr-render-error` with `detail.error` when fetching or parsing fails.
+
+**CSS parts:** `base`, `body`, `contact`, `contact-name`, `contact-org`, `contact-tel`,
+`contact-email`, `contact-adr`, `spinner`, and `error`.
+
+**Themeable custom properties:** `--lr-contact-viewer-max-height` (default `none`) — maximum block
+size of `[part="body"]`; also settable via the `max-height` property, which writes this token inline.
+
+**Exports:** `parseVCards()` and the `VCardName`, `VCardTypedValue`, `VCardAddress`, and `VCardContact`
+types.

package/llms/components/lr-context-inspector.md

@@ -0,0 +1,50 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/agent-tools.md — do not edit this file. -->
+
+# `lr-context-inspector`
+
+- **Import** `import '@aceshooting/lyra-ui/components/agent-tools/context-inspector/context-inspector.js';` (registers the tag; side-effect import)
+- **Class** `LyraContextInspector`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/context-inspector/context-inspector.class.js`
+- **Family** `components/agent-tools/` — 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-context-inspector`
+
+Inspection view of model-call context segments, with token estimates, source citations, redaction
+markers, and copy/export controls.
+
+**Properties:**
+- `segments: ContextInspectorSegment[] = []` (attribute: false) — `ContextInspectorSegment { id:
+  string; label: string; text: string; tokens: number; tone?: ContextMeterTone; citation?: Citation;
+  truncated?: boolean; omittedTokens?: number; redactions?: ContextInspectorRedaction[] }` (exported
+  here). One entry per piece of the assembled final prompt (system prompt, retrieved chunk, one
+  history turn, …). `text` is the segment's **final** text, exactly as sent to the model
+  (post-redaction/post-truncation). `tokens` is the estimated count, fed straight to
+  `lr-context-meter`'s segment `value`; `label` feeds both the segment heading and the meter's
+  segment label. `citation` is **`Citation` from `@aceshooting/lyra-ui/ai`** and renders an
+  `lr-citation-badge` carrying its `sourceId`/`label`. `omittedTokens` is shown in the
+  truncation-boundary marker when `truncated` is set. `ContextInspectorRedaction { start: number;
+  end: number; reason?: string }` marks character ranges within `text` that are redaction
+  placeholders; `reason` becomes the marker's `title`/accessible reason, falling back to a localized
+  "Redacted"
+- `total: number = 0` — the full token budget `segments` are measured against; passed straight to
+  `lr-context-meter.total`
+- `label: string = ''` — accessible group name, and the embedded meter's visible caption (e.g.
+  "128K context window")
+- `formats: ExportFormatOption[] = ['json']` (attribute: false) — forwarded to the embedded
+  `lr-export-button`; one id renders a plain button, more than one a format-choice menu
+- `filename: string = 'context'` — download filename (no extension) passed to `lr-export-button`
+
+**Events:** `lr-citation-activate` (`detail: { sourceId: string; index: number }`, surfaced by a
+segment's embedded `lr-citation-badge`), `lr-citation-open` (`detail: { sourceId: string; index:
+number; href?: string }`, the "full preview" signal), `lr-copy` (`detail: { text: string }`, from the
+embedded `lr-copy-button`), `lr-export` (`detail: { format: string }`, from the embedded
+`lr-export-button`), `lr-export-complete` (`detail: { format: string }`, after a non-cancelled export
+finishes).
+
+**CSS parts:** `base`, `toolbar`,
+`segments`, `segment`, `segment-header`, `segment-label`, `segment-text`, `segment-tokens`,
+`meter` (the embedded `lr-context-meter`), `citation`, `redaction` (one redaction placeholder
+marker), `truncation-boundary`, `copy-button`, `export-button`, `empty`.