@aceshooting/lyra-ui 5.0.0 → 5.2.0

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

@@ -0,0 +1,165 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/conversation.md — do not edit this file. -->
+
+# `lr-code-block`
+
+- **Import** `import '@aceshooting/lyra-ui/components/conversation/code-block/code-block.js';` (registers the tag; side-effect import)
+- **Class** `LyraCodeBlock`, also available unregistered from `@aceshooting/lyra-ui/components/conversation/code-block/code-block.class.js`
+- **Family** `components/conversation/` — see `llms/index.md` for its siblings
+- **Optional peers** `shiki` — see `llms/peers.md`
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-code-block`
+
+Fenced code display with optional lazy syntax highlighting and a copy button. First-party invention
+(no Web Awesome equivalent). It lazy-loads the optional peer dependency `shiki` (see
+`code-loader.ts`) for the actual tokenizing, and includes a compact GreyCat/GCL grammar because
+Shiki does not bundle one. It falls back to a plain `<pre><code>` when that peer isn't installed or
+`language` is unset/unrecognized. That
+fallback is the *default* rendering path, not a degraded one: unhighlighted code is perfectly usable,
+and it's what every instance renders at zero extra bytes until shiki resolves.
+
+**Properties:**
+- `code: string = ''` — the raw source text
+- `language: string = ''` — a shiki-recognized language id or alias (e.g. `"javascript"`, `"python"`,
+  `"json"`); when unset, or when shiki doesn't recognize it, the code renders as plain unhighlighted
+  text regardless of whether shiki itself is available. Shiki's bundled catalog covers most common
+  programming, markup, data, and configuration languages, including Python, C, C++, C#, Java,
+  JavaScript, TypeScript, HTML, CSS, JSON, SQL, Go, Rust, YAML, Markdown, and shell scripts. Lyra
+  also includes a built-in GreyCat grammar; use `"gcl"` or `"greycat"` for GreyCat source.
+- `filename: string = ''` — shown in the header, when set
+- `accessibleLabel: string = ''` (attribute `aria-label`) — names the internal focusable code-body
+  region; otherwise a localized filename/language description is generated
+- `collapsible: boolean = false` (reflected) — shows the collapse/expand chevron button
+- `collapsed: boolean = false` (reflected) — only has a visible effect while `collapsible` is also
+  true
+- `copyable: boolean = true` (reflected) — shows the copy-to-clipboard button (assign `false` via a
+  PROPERTY binding, e.g. `.copyable=${false}` — a `?copyable=${false}` boolean-attribute binding
+  cannot override a true default)
+- `maxHeight: string = ''` (attribute `max-height`) — a CSS length (e.g. `"20rem"`); once set, the
+  code scrolls internally past this height instead of growing the page
+- `lineNumbers: boolean = false` (attribute `line-numbers`, reflected) — displays one-based line
+  numbers for both highlighted output and the plain-text fallback
+- `highlightLines: string = ''` (attribute `highlight-lines`) — comma-separated 1-based inclusive
+  line ranges (e.g. `"3-5,7"`) to visually emphasize. Declarative sugar over `highlights` — merges
+  with, and renders identically to, any `line-range` entries there.
+- `interactiveLines: boolean = false` (attribute `interactive-lines`) — turns the
+  (`lineNumbers`-gated) gutter into a roving-tabindex group of buttons emitting `lr-line-click`.
+  Has no effect while `lineNumbers` is unset.
+- `highlights: LyraHighlight[] = []` (attribute: false) — host-supplied highlights to paint over the
+  code (the shared anchor-target `LyraHighlight` contract from `document-viewer/anchors.ts`). Only
+  `line-range` anchors are meaningful here — every other `LyraAnchor` kind is ignored.
+- `activeHighlightId: string | null = null` (attribute `active-highlight-id`) — the `highlights`
+  entry, if any, currently treated as active (`data-active` on its lines).
+- `anchorKinds: LyraAnchor['kind'][]` — readonly `['line-range']`, for the shared anchor-target
+  contract.
+- `languages?: Record<string, ShikiLanguageInput>` (attribute: false) — a map of language id to an
+  already-imported shiki grammar module (e.g. `{ bash: bashGrammar }` from a module-scope
+  `import bash from 'shiki/langs/bash.mjs'`). When `language` matches a key here, highlighting is
+  seeded from exactly that pre-supplied grammar via a fine-grained `createHighlighterCore()`
+  highlighter, bypassing the default ~200-language dynamic-import path (`loadShikiHighlighter()`)
+  for that language — an additive, opt-in escape hatch for a build scoped to just the languages a
+  consumer actually needs. A `language` absent from this map (or `languages` left unset) falls back
+  to the default dynamic-import path unchanged.
+- `languagesOnly: boolean = false` (attribute `languages-only`) — skips the default shiki loader;
+  use when every requested language is supplied through `languages`
+
+**Methods:** `scrollToAnchor(target)` — resolves a `line-range` anchor (or a `highlights` id string
+resolving to one) by scrolling its start line into view within `[part="body"]`; resolves `false`
+when the anchor isn't a `line-range`, the id isn't found, or the start line is out of bounds.
+
+**Events:** `lr-copy` (`detail: { text: string }` — always the raw `code` value, never the
+highlighted HTML, and always fires regardless of whether the actual OS clipboard write succeeded),
+`lr-toggle` (`detail: { collapsed: boolean }` — fired when the built-in collapse/expand header
+button is activated, same event name/shape convention as `<lr-thinking-panel>`'s own `lr-toggle`),
+`lr-line-click` (`detail: { line: number }` — a gutter line number was activated while
+`interactiveLines` is set), `lr-highlight-activate` (`detail: { id: string }` — declared for
+parity with this library's other anchor-target viewers; not currently emitted by this component),
+`lr-text-select` (`detail: { text, anchor, rects }` — a text selection inside the code body ended;
+`anchor` is a `line-range` anchor covering the selected lines)
+
+**Slots:** none.
+
+**CSS parts:** `base`, `header`, `filename`, `language`, `copy-button`, `toggle`, `body`, `pre`,
+`code`, `line-highlight` (a line marked by `highlightLines` or a `line-range` entry in `highlights`),
+`line-button` (a gutter line-number button, only rendered while `interactiveLines` and `lineNumbers`
+are both set)
+
+**Themeable custom properties:** `--lr-code-block-max-height` (default `none` — the consumer-tunable
+scroll cap; only takes effect once `max-height` is set), `--lr-code-block-font` (default
+`ui-monospace, SFMono-Regular, Menlo, Consolas, monospace` — no shared `--lr-*` monospace
+token exists to resolve through), `--lr-code-block-tab-size` (default `2` — tab width for the
+rendered code, applied to `[part='pre']`), `--lr-code-block-active-line-outline-color` (default
+`var(--lr-color-brand)` — the outline around the line marked active by `active-highlight-id`), plus shared tokens `--lr-color-border`, `--lr-radius`,
+`--lr-color-surface`, `--lr-space-xs/-s/-m`, `--lr-font`, `--lr-color-text-quiet`,
+`--lr-color-text`, `--lr-color-brand`/`-brand-quiet`, `--lr-transition-fast`,
+`--lr-focus-ring-width/-color/-offset`.
+
+`--lr-code-block-tab-size` carries the same default as `--lr-code-editor-tab-size`, so the editable
+and read-only code surfaces agree on what a literal tab looks like. It is declared as a `var()`
+fallback **at the point of use, not on `:host`** — a `:host` rule is re-stamped on every instance and
+shadows any inherited value, so a page- or container-level declaration could never reach it. It is
+also never written as an inline `tab-size`: `shiki` puts its own `style` attribute on the highlighted
+`<pre>`, and an inline declaration is the one thing a host override cannot beat. `<lr-markdown>` and
+`<lr-markdown-core>` carry the same fallback for their own `code-block` part because they are
+**sibling** custom elements rather than descendants of this one — no single declaration covers both.
+The identical value can still look different across the two: this component is `white-space: pre`
+while a markdown code block inherits `pre-wrap`, and tab stops restart at each visual line, so a
+wrapped line's tabs diverge.
+
+`--lr-code-block-active-line-outline-color` retints just the active line's outline and leaves every
+other `--lr-color-brand` surface in the component — the header language pill, hover states, the focus
+ring — alone. It too is an inline `var()` fallback rather than a `:host` declaration, deliberately,
+so it inherits: set it on the element, on an ancestor, or at the theme level.
+
+**Optional peer deps:** `shiki` (lazy-loaded and cached once per page by `code-loader.ts`'s
+`loadShikiHighlighter()`, which builds a single `Highlighter` seeded with the bundled `github-light`/
+`github-dark` "dual themes" and *zero* language grammars up front; each `language` a
+`<lr-code-block>` actually requests is loaded incrementally on first use via
+`loadShikiLanguage()`, and a language id that fails to load once is remembered and never retried. If
+`shiki` isn't installed, `loadShikiHighlighter()` resolves to `null` with a one-time `console.warn`
+and every instance falls back to plain text — install it with `pnpm add shiki` to enable
+highlighting).
+
+```html
+<lr-code-block
+  language="typescript"
+  filename="sum.ts"
+  collapsible
+  max-height="20rem"
+  .code=${`export function sum(a: number, b: number) {\n  return a + b;\n}`}
+  @lr-copy=${(e) => console.log('copied', e.detail.text)}
+></lr-code-block>
+```
+
+Set `line-numbers` when source context benefits from numbered lines. The option does not change the
+raw `code` value or the `lr-copy` event payload.
+
+A `<lr-skeleton variant="rect">` placeholder (with `aria-busy="true"` on the host) stands in only
+while shiki itself is loading for the very first time on the page and `language` is set — it is
+deliberately *not* shown again for a later per-language grammar fetch (that's typically fast, and the
+plain-text fallback already reads fine as a placeholder for it). Internally, a shiki `transformer`
+(`partTransformer`) rewrites shiki's generated `<pre>`/`<code>` nodes in a single pass to carry this
+component's own `part="pre"`/`part="code"` hooks and strips shiki's default `tabindex="0"` from
+`<pre>`, since `[part="body"]` is already the single scrollable/focusable region (`role="group"`,
+`tabindex="0"`) for the code area. Dark mode is handled via shiki's own "dual themes" feature: every
+token carries its light color as a plain inline `color`/`background-color` and its dark color in
+`--shiki-dark`/`--shiki-dark-bg` custom properties, which an `!important` media-query rule in
+`code-block.styles.ts` reassigns under `prefers-color-scheme: dark` — the one deliberate exception in
+this component to every other color being a `--lr-*` token, since these values come from shiki's own
+theme data.
+
+**Known gotchas:**
+- `copyable` defaults to `true` and reflects — see the property note above about overriding it with a
+  property binding, not a boolean-attribute binding.
+- an in-flight per-language grammar load is guarded by an internal token so a `code`/`language` change
+  that arrives before a previous load resolves never applies a stale result — only the load matching
+  the *current* `language` is ever rendered.
+- a malformed `code`/`language` combination that makes shiki's `codeToHtml()` throw falls back to
+  plain text silently, not a blank code block.
+- the "Copied!" label reverts to "Copy" after a fixed 1500ms, regardless of whether the clipboard
+  write actually succeeded — `navigator.clipboard` is absent in insecure contexts/older browsers, and
+  `lr-copy` still fires either way.
+
+---

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,231 @@
+<!-- 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 there is something to
+  clear on **either** axis this control owns: a committed selection, or *visible* filter text. See
+  "the clear button covers two axes" below
+- `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.
+
+**The clear button covers two axes, and announces only the one that moved.** A combobox owns both a
+committed selection and an in-progress filter query, so the button renders whenever either has
+something to clear, and one press clears both:
+
+- Clearing a selection emits `input`, then `change`, then `lr-clear` — and, if the query was also
+  non-empty, `lr-filter` with an empty `value`.
+- A **query-only** clear (nothing selected, just typed text) emits `lr-filter` with an empty
+  `value` and deliberately **no** `change` and **no** `lr-clear`. There was no selection
+  transition to report, so announcing one would be a lie. Don't listen for `lr-clear` to detect
+  "the user emptied the field" — listen for `lr-filter` when you care about the query.
+- The query half of the render gate is scoped to states where the query is actually *visible*: an
+  open listbox in single-select, or any time in `multiple` mode. A closed single-select shows the
+  selected label rather than the query, so a stale query alone never surfaces a button offering to
+  clear text the user cannot see.
+
+**Slots:** default (`<lr-option>` children), `label`, `hint`, `error` (overrides the `errorText`
+attribute when provided), plus two adornment slots:
+- `start` — content at the inline-start of the trigger row, before the selected-value tags and the
+  filter input. It is decorative chrome, **not** an option: only `<lr-option>` elements in the
+  default slot are ever collected into the option list.
+- `end` — content after the filter input and the built-in clear action, and before the expand icon,
+  so consumer content never sits outboard of the dropdown chevron.
+
+**CSS parts:** `form-control`, `form-control-label`, `combobox`, `start` and `end` (the two
+adornment-slot wrappers, each `hidden` while nothing is slotted into it), `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.
+
+`--lr-combobox-option-active-bg` (default `var(--lr-color-brand-quiet)`) recolors the background of
+a hovered or keyboard-active `[part='option']` row — the same per-component indirection
+`lr-select`'s identical `--lr-select-option-active-bg` uses, so a consumer can retheme just this
+row state without hijacking the shared `--lr-color-brand-quiet` token library-wide.
+
+`--lr-combobox-trigger-height` pins an **exact** input-container height (both floors and caps it),
+for pixel-matching an `<lr-input>` or `<lr-select>` in the same toolbar row. It is **undeclared by
+default**, leaving `--lr-combobox-trigger-min-height` as a floor only and the row free to grow —
+see "exact-height hatches" under `lr-input` for why `auto` is not a way to opt back out. Intended
+for a single-row combobox: in `multiple` mode, a tag row long enough to wrap overflows the pinned
+box visibly (nothing is clipped or made unreachable), so leave it unset there.
+
+**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,61 @@
+<!-- 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?, icon?, onSelect? }`. `icon` is an optional leading glyph (a `TemplateResult`,
+  an emoji string, etc. — not restricted to a square icon) rendered in the `icon` part before the
+  label; a command with no `icon` renders no `icon` part at all. 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), `icon` (a command's leading icon glyph; only
+rendered when the command has one), `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`),
+`--lr-command-palette-list-max-block-size` (default `50vh` — the scrolling result list), and
+`--lr-command-palette-active-bg` (default `var(--lr-color-brand-quiet)` — the background of the
+active, keyboard-highlighted command row). That last one is an inline `var()` fallback at the point
+of use rather than a `:host` declaration, so it can be set on the element *or on any ancestor*:
+`::part(command)[data-active='true']` is invalid CSS (Shadow Parts forbids an attribute selector
+after `::part()`), so highlighting the active row previously required hijacking the library-wide
+`--lr-color-brand-quiet` token and repainting everything else that read it. Unset, it falls back to
+that token, so rendering is unchanged.

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

@@ -0,0 +1,43 @@
+<!-- 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).
+`compact: boolean = false` (reflected) — tighter `[part="base"]` padding for a commit rendered as a
+row in a list or PR timeline, same convention as `<lr-agent-run>`'s own `compact`; the border stays,
+so pair it with `appearance="plain"` to drop the chrome entirely. `appearance: 'card' | 'plain' =
+'card'` (reflected) — mirrors `lr-card`'s/`<lr-agent-run>`'s `appearance` vocabulary: `'card'` keeps
+the bordered, padded box, `'plain'` removes the border, padding, and corner radius so a commit nested
+in a host list that already draws its own row chrome doesn't double it; `plain` wins over `compact`
+when both are set.
+
+**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`.
+
+**Themeable custom properties:** `--lr-commit-card-compact-padding` (default `var(--lr-space-s)`) —
+`[part="base"]` padding while `compact`.