@aceshooting/lyra-ui 5.0.0 → 5.1.0

package/llms/components/lr-chip.md

@@ -0,0 +1,152 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/overlays.md — do not edit this file. -->
+
+# `lr-chip`
+
+- **Import** `import '@aceshooting/lyra-ui/components/overlays/chip/chip.js';` (registers the tag; side-effect import)
+- **Class** `LyraChip`, also available unregistered from `@aceshooting/lyra-ui/components/overlays/chip/chip.class.js`
+- **Family** `components/overlays/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Documented with** `lr-chip-group` (same section below)
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-chip` / `lr-chip-group`
+
+A small, content-agnostic pill for a short label: a tag, an active-filter/scope indicator, etc.
+Distinct from `<lr-attachment-chip>` (specifically file-shaped, with a thumbnail/size/upload-
+progress) — this pair carries no domain assumptions at all. `<lr-chip>` is a controlled component:
+clicking its remove (×) button only fires `lr-remove` — the chip never removes itself from the DOM
+on its own interaction, the same contract `<lr-attachment-chip>`/`<lr-conversation-item>`
+already follow.
+
+### `lr-chip`
+
+**Properties:**
+- `size: '2xs' | 'xs' | 's' | 'm' | 'l' | 'xl' = 'm'` (reflected) — standard visual-density
+  scale for typography, padding, gap, and icon size; `m` preserves the original chip dimensions
+- `tone: 'neutral' | 'brand' | 'success' | 'warning' | 'danger' = 'neutral'` (reflected — tints the
+  whole pill using a loud-color-on-quiet-tint convention; `neutral` has no dedicated token pair, so
+  it falls back to a plain bordered-surface look)
+- `removable: boolean = false` (reflected — shows the remove (×) button)
+- `selected: boolean = false` (reflected) — opt-in toggle/pressed mode: when set, `[part='base']`
+  itself becomes focusable and keyboard-activatable (Enter/Space, mirroring native `<button>`
+  behavior), reflects `aria-pressed` (explicitly `"false"`, not omitted, whenever toggle mode is
+  active but unpressed), and toggles on click/activation, emitting `lr-chip-select`.
+  Has no effect (no interactive semantics added to `[part='base']`) when combined with `removable`,
+  since the remove button already nests inside `[part='base']` — a focusable descendant of a
+  `role="button"` ancestor isn't allowed there, and this component's two real use cases (a
+  chart-series visibility toggle, a category filter chip) never need both at once. `false` (the
+  default, with `toggleable` also left at its default) reproduces the exact passive-label-pill
+  output.
+- `toggleable: boolean = false` (reflected) — explicit opt-in into `selected`'s toggle/pressed
+  interactive mode, independent of `selected`'s own current value. Setting `selected` to `true` at
+  any point opts in automatically and keeps `toggleable` `true` from then on (enough for a chip that
+  starts already pressed) — set `toggleable` directly instead for a chip that must be clickable from
+  the outset while starting **unselected**, e.g. an initially-inactive category filter chip, since
+  `selected`'s own default (`false`) can't otherwise be distinguished from "never opted in".
+- `value?: string` — opaque consumer bookkeeping value, never read, validated, or rendered by this
+  component itself, only ever echoed back verbatim (including `undefined` if never set) in
+  `lr-remove`'s detail
+
+**Events:** `lr-remove` (`detail: { value }` — the remove (×) button was activated via click or
+Enter/Space while focused; only rendered/reachable while `removable`), `lr-chip-select`
+(`detail: { value, selected }` — fired on click, or Enter/Space while focused, when `selected` mode
+is active and `removable` is not set; the chip has already toggled its own `selected` state by the
+time this fires)
+
+**Slots:** default (the chip's label content), `icon` (optional leading icon or status dot; nothing
+reserved for it — no extra gap — when left empty)
+
+**CSS parts:** `base` (the pill's root container), `icon` (wrapper around the `icon` slot; hidden
+entirely while empty), `label` (wrapper around the default slot), `remove-button` (the remove (×)
+affordance, only rendered while `removable`)
+
+**Themeable custom properties:** `--lr-chip-accent`, `--lr-chip-bg`, `--lr-chip-border`
+(component-local trio swapped per `tone` rather than repeating background/color/border per part per
+tone; default `var(--lr-color-text)` / `var(--lr-color-surface)` / `var(--lr-color-border)` —
+mirrors the same accent/bg/border vocabulary `<lr-tool-call-chip>`/`<lr-attachment-chip>` use),
+`--lr-chip-pressed-border` (border color while pressed/selected — falls back to
+`--lr-chip-accent`), `--lr-chip-pressed-bg` (background color while pressed/selected — falls
+back to `--lr-chip-bg`), the density quintet `--lr-chip-font-size`, `--lr-chip-padding-block`,
+`--lr-chip-padding-inline`, `--lr-chip-gap`, `--lr-chip-icon-size` (all five are rewritten by each
+`:host([size])` rule, so setting one directly on the element overrides that step of the scale; the
+`m` defaults are `--lr-font-size-sm` / `--lr-size-0-25rem` / `--lr-space-s` / `--lr-space-xs` /
+`--lr-font-size-sm`), plus shared tokens (`--lr-space-xs`, `--lr-space-s`,
+`--lr-color-brand`/`-brand-quiet`, `--lr-color-success`/`-success-quiet`,
+`--lr-color-warning`/`-warning-quiet`, `--lr-color-danger`/`-danger-quiet`,
+`--lr-icon-button-size`, `--lr-focus-ring-width`, `--lr-focus-ring-color`,
+`--lr-focus-ring-offset`, `--lr-transition-fast`).
+
+**Optional peer deps:** none.
+
+```html
+<lr-chip
+  toggleable
+  selected
+  style="--lr-chip-bg: var(--lr-color-surface); --lr-chip-pressed-bg: var(--lr-color-warning-quiet)"
+>
+  Priority filter
+</lr-chip>
+```
+
+### `lr-chip-group`
+
+A flex-wrap container for a set of `<lr-chip>` children — plain light-DOM composition, direct
+children are the chips (the same shape `<lr-split>`'s panels / `<lr-source-list>`'s cards take,
+no `.items` array prop).
+
+**Properties:**
+- `maxVisible?: number` (attribute `max-visible`) — maximum number of assigned children shown before
+  the rest collapse behind a "+N" indicator; flattened slot-forwarded children count the same as
+  direct children. Unset means no limit
+
+**Events:** `lr-overflow-toggle` (`detail: { expanded }` — the overflow indicator was activated,
+revealing or re-collapsing the excess children; fires only from that click, i.e. only when
+`max-visible` is actually causing an overflow state — never as a side effect of `max-visible`/
+children changing on their own)
+
+**Slots:** default (`<lr-chip>` elements, or any content, though the chip pairing is the intended
+usage)
+
+**CSS parts:** `base` (the flex-wrap container, holds both the slot and the overflow indicator),
+`overflow-indicator` (the "+N" / "Show less" toggle button; only rendered while `max-visible` is
+actively causing an overflow — a locally-styled pill, not an instantiated real `<lr-chip>`)
+
+**Themeable custom properties:** shared tokens only (`--lr-space-xs`, `--lr-space-s`,
+`--lr-color-border`, `--lr-color-surface`, `--lr-color-text-quiet`, `--lr-color-text`,
+`--lr-color-brand`, `--lr-focus-ring-width`, `--lr-focus-ring-color`,
+`--lr-focus-ring-offset`, `--lr-transition-fast`).
+
+**Optional peer deps:** none.
+
+```html
+<lr-chip-group max-visible="3">
+  <lr-chip removable value="draft">Draft</lr-chip>
+  <lr-chip tone="success" removable value="reviewed">Reviewed</lr-chip>
+  <lr-chip tone="warning">Needs input</lr-chip>
+  <lr-chip tone="danger">Blocked</lr-chip>
+</lr-chip-group>
+<script type="module">
+  const group = document.querySelector('lr-chip-group');
+  group.addEventListener('lr-overflow-toggle', (e) => console.log(e.detail.expanded));
+  group.querySelectorAll('lr-chip').forEach((chip) => chip.addEventListener('lr-remove', (e) => console.log(e.detail.value)));
+</script>
+```
+
+Since CSS alone can't parameterize `:nth-child` on a runtime prop, `<lr-chip-group>` reaches
+directly into the light DOM and sets each excess child's own `hidden` property once `max-visible` is
+exceeded — the same approach `<lr-split>` uses to set each panel's inline `flex`/`order`, rather
+than a stylesheet-only solution.
+
+**Known gotchas:**
+- `<lr-chip>`'s accessible remove-button label ("Remove {text}") is computed only from the default
+  slot's own text content — text living inside the (decorative) `icon` slot doesn't leak into it.
+- `<lr-chip-group>` silently un-expands (`expanded` resets to `false`, with no event firing) if a
+  consumer raises `max-visible` past the current child count while already expanded — only an actual
+  click on the overflow indicator fires `lr-overflow-toggle`.
+- `<lr-chip-group>`'s overflow indicator is its own locally-styled pill, not an instantiated
+  `<lr-chip>` in its shadow DOM — don't expect `<lr-chip>`'s CSS parts or custom properties to
+  reach it.
+
+---

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

@@ -0,0 +1,66 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/retrieval.md — do not edit this file. -->
+
+# `lr-chunk-inspector`
+
+- **Import** `import '@aceshooting/lyra-ui/components/retrieval/chunk-inspector/chunk-inspector.js';` (registers the tag; side-effect import)
+- **Class** `LyraChunkInspector`, also available unregistered from `@aceshooting/lyra-ui/components/retrieval/chunk-inspector/chunk-inspector.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-chunk-inspector`
+
+A ranked retrieved-chunks list: relevance score bars with tier tones, expandable chunk text, and the
+deep-link event that lands a chunk in `lr-document-viewer`. Never fetches, ranks, or dedupes; never
+opens documents itself.
+
+**Properties:**
+- `chunks: LyraChunk[] = []` (attribute: false) — `LyraChunk { id: string; text: string; score:
+  number; sourceId: string; title?: string; page?: string | number; anchor?: LyraChunkAnchor }`;
+  `score` is 0–1, `title` falls back to a localized "untitled source", `anchor` (the same
+  discriminated union `lr-document-viewer.anchor` accepts — page/text-quote/fragment/line-range/
+  cell-range/cfi/time-range/region/node-path) is carried through `lr-chunk-open` verbatim
+- `thresholds: { high: number; medium: number } = { high: 0.75, medium: 0.5 }` (attribute: false) —
+  score-bar tier cutoffs
+- `sort: 'score' | 'none' = 'score'`
+- `activeId: string = ''` (attribute `active-id`)
+- `virtualizeAt: number = 50` (attribute `virtualize-at`)
+- `compact: boolean = false` (reflected) — hides the text preview/toggle, title/score row only
+- `label: string = ''`
+
+**Events:** `lr-chunk-open` (`detail: { id, sourceId, anchor? }`, a chunk's title/open button was
+activated — the event a host routes into `lr-document-viewer`, setting `src` from `sourceId` and
+`anchor` from the chunk's own), `lr-expand` (`detail: { id, expanded }`, a chunk's text toggle was
+activated).
+
+**Slots:** none.
+
+**CSS parts:** `base` (`role="group"`), `chunk` (`role="listitem"`), `score` (visible percent text),
+`score-bar` (`aria-hidden` track), `score-fill` (tone-mapped fill), `open-button`, `title` (the
+`<span>` inside `open-button` carrying the visible title text), `text` (line-clamped unless
+expanded, omitted when `compact`), `toggle` ("Show more"/"Show less", omitted when `compact`),
+`empty` (shown when `chunks` is empty).
+
+**Themeable custom properties:** shared tokens only.
+
+**Optional peer deps:** none.
+
+```html
+<lr-chunk-inspector></lr-chunk-inspector>
+<script>
+  const inspector = document.querySelector('lr-chunk-inspector');
+  inspector.chunks = [
+    { id: 'c1', text: 'Revenue grew 12% year over year…', score: 0.91, sourceId: 'doc-1', title: 'Q3 report', page: 4 },
+  ];
+  inspector.addEventListener('lr-chunk-open', (e) => documentViewer.openAt(e.detail.sourceId, e.detail.anchor));
+</script>
+```
+
+**Known gotchas:**
+- `title` and `open-button` are split into two separate parts (rather than one dual-part-name
+  element) because an exact-match `[part="..."]` CSS attribute selector — as this component's own
+  tests use — cannot match a multi-token `part` attribute value.
+
+---

package/llms/components/lr-citation-badge.md

@@ -0,0 +1,102 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/retrieval.md — do not edit this file. -->
+
+# `lr-citation-badge`
+
+- **Import** `import '@aceshooting/lyra-ui/components/retrieval/citation-badge/citation-badge.js';` (registers the tag; side-effect import)
+- **Class** `LyraCitationBadge`, also available unregistered from `@aceshooting/lyra-ui/components/retrieval/citation-badge/citation-badge.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-citation-badge`
+
+An inline `[n]` citation marker with a hover/focus preview popover and confidence/verification-status
+coloring. First-party invention (no Web Awesome equivalent). Meant to sit inline in a chat message's
+text, each badge carrying a `source-id` that matches a corresponding `<lr-source-card>` shown
+elsewhere on the page (a sibling component in this family) — this component never imports or knows
+anything about `<lr-source-card>`, it only carries the id through its event details.
+
+**Properties:**
+- `index: number = 1` — the citation number shown, e.g. `3` renders as `[3]`.
+- `status: CitationBadgeStatus = 'default'` (reflected) — one of `'default' | 'high' | 'medium' |
+  'low' | 'verified' | 'unverified'`; drives the badge's color and (unless `label` is set) part of
+  its accessible name.
+- `sourceId: string = ''` (attribute `source-id`) — id of a corresponding `<lr-source-card>`,
+  echoed back verbatim in both events; never read or validated by this component.
+- `href: string = ''` — optional direct link target for the citation's source, carried into
+  `lr-citation-open`'s detail as-is; this component never navigates.
+- `label: string = ''` — overrides the computed accessible name. The built-in citation/status
+  summary is a complete localized template; a host `aria-label` has highest precedence.
+
+**Events:**
+- `lr-citation-activate` (`detail: { sourceId: string; index: number }`) — fires on click, or on
+  Enter while focused (native `<button>` behavior, no listener needed for the Enter case). The
+  lightweight "jump to this source" signal.
+- `lr-citation-open` (`detail: { sourceId: string; index: number; href?: string }`) — fires on
+  dblclick, or on Space while focused. A distinct "full preview" signal; `href` is `undefined` when
+  the `href` prop isn't set. A double-click also fires two `lr-citation-activate` events (one per
+  constituent click, standard browser `dblclick` behavior) in addition to the one `lr-citation-open`.
+
+**Slots:** default — rich preview/tooltip content (e.g. a filename + excerpt), shown in a floating
+popover on hover/focus. This is *not* the badge's visible content (the badge always renders
+`[index]`); nothing renders at all (no hover affordance) when this slot is empty.
+When populated, the button carries `aria-describedby` referencing the same-shadow-tree popover,
+which owns `role="tooltip"` whether currently shown or hidden.
+
+**CSS parts:** `base` (the clickable `<button>`), `bracket` (each of the two literal `[`/`]` glyphs),
+`index` (the citation number), `popover` (the floating preview panel, only meaningful while open).
+
+**Themeable custom properties:** `--lr-citation-badge-accent` / `--lr-citation-badge-bg` /
+`--lr-citation-badge-border` (internal per-status accent variables, not typically overridden
+directly — set instead by the `:host([status=...])` rules), plus shared tokens
+`--lr-color-text-quiet`, `--lr-color-text`, `--lr-color-success` / `-success-quiet`,
+`--lr-color-warning` / `-warning-quiet`, `--lr-color-danger` / `-danger-quiet`, `--lr-radius`,
+`--lr-color-surface`, `--lr-color-border`, `--lr-shadow`, `--lr-space-s`/`-m`,
+`--lr-transition-fast`, `--lr-focus-ring-*`.
+
+**Optional peer deps:** none.
+
+```html
+<p>
+  Revenue grew 12% year over year
+  <lr-citation-badge index="1" status="verified" source-id="doc-1">
+    <strong>annual_report.pdf</strong> — "Revenue grew 12% year over year, driven primarily by..."
+  </lr-citation-badge>.
+</p>
+<script type="module">
+  document.addEventListener('lr-citation-activate', (e) => {
+    document.querySelector(`lr-source-card[source-id="${e.detail.sourceId}"]`)
+      ?.scrollIntoView({ behavior: 'smooth', block: 'center' });
+  });
+</script>
+```
+
+The popover is positioned with the same internal `place()` helper (`top-start` placement) that
+`<lr-tool-call-chip>` uses for its own detail tooltip, and never traps focus — it's supplementary
+preview content, not a modal, so Tab continues past the badge normally even while the popover happens
+to be visible from a mouse hover. Hovering and focus are tracked as independent "keep it open"
+reasons (mirroring `<lr-toast-item>`'s hovering/focused pair), so the pointer leaving while the
+badge still holds keyboard focus doesn't schedule a hide the focus is still holding open. There's a
+200ms grace period before a hover/focus-out actually hides the popover, so moving the pointer from
+the badge into the popover itself (to select/copy its text) doesn't make it vanish mid-move; Escape
+and blur (Tab away) close it immediately instead, with no delay.
+
+Status coloring follows a semantic scheme: `verified`/`high` use the success tones (a claim that's
+been checked, or the model is confident in); `medium`/`low` use warning tones; `unverified` uses the
+*danger* tone — deliberately distinct from `low`, since "hasn't been checked at all" is a different
+(arguably riskier) claim than "checked but uncertain". `default` renders as plain neutral text with
+no background tint, for citations that carry no confidence/verification signal at all.
+
+**Known gotchas:**
+- Enter and Space are given distinct meanings (Enter = activate via native `<button>` click, Space =
+  open) — Space's native click-on-keyup is pre-empted with `preventDefault()` on keydown so it fires
+  `lr-citation-open` instead of triggering a second `lr-citation-activate`.
+- Escape closes the popover but calls `stopPropagation()`, so it won't also close a surrounding
+  `<lr-dialog>` that has its own Escape-to-close handler.
+- The preview slot's presence is tracked in JS (`hasPreviewSlot`), not via CSS `:empty` — the
+  `[part="popover"]` always contains a literal `<slot>` child, so `:empty` would never match even
+  with nothing assigned.
+
+---

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

@@ -0,0 +1,113 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/conversation.md — do not edit this file. -->
+
+# `lr-code-block-core`
+
+- **Import** `import '@aceshooting/lyra-ui/components/conversation/code-block/code-block-core.js';` (registers the tag; side-effect import)
+- **Class** `LyraCodeBlockCore`, also available unregistered from `@aceshooting/lyra-ui/components/conversation/code-block/code-block-core.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-core`
+
+A build-lean sibling of `<lr-code-block>` above, for a consumer whose `languages` map already
+covers every language it will ever render. Where `<lr-code-block>` unconditionally calls
+`loadShikiHighlighter()` — the default ~200-language dynamic-import table loader, whose bundled
+lookup table a bundler can't statically narrow away even when a consumer never actually uses it —
+this component's own module never imports or calls that function at all. It only ever calls
+`loadShikiHighlighterCore(languages)` (shiki's "fine-grained bundle" recipe: `createHighlighterCore()`
+plus an explicit oniguruma engine, seeded with *only* the grammars in `languages`), so a consumer
+importing this entry point instead of `code-block.js` gets a build genuinely free of shiki's full
+language table.
+
+A `language` value absent from `languages` always renders the plain `<pre><code>` fallback — there is
+no default/full-table highlighter here to fall back to, unlike `<lr-code-block>`'s dynamic-import
+path for an unmapped language. That fallback is the *default* rendering path, not a degraded one,
+same as `<lr-code-block>`'s own plain-text fallback. Everything else — `code`/`language`/
+`filename`/`copyable`/`collapsible`/`collapsed`/`maxHeight`, the copy button, the collapse header
+toggle, the loading-skeleton behavior while the fine-grained highlighter resolves — matches
+`<lr-code-block>` exactly, including its CSS parts, themeable custom properties, and stylesheet
+(this component reuses `code-block.styles.ts` directly).
+
+**Properties:**
+- `code: string = ''` — the raw source text.
+- `language: string = ''` — a shiki-recognized language id or alias; when unset, or when it isn't a
+  key in `languages`, the code renders as plain unhighlighted text — this component has no
+  default/full-table highlighter to fall back to.
+- `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.
+- `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 highlighted and plain output.
+- `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. 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, identical to `<lr-code-block>`.
+- `languages: Record<string, ShikiLanguageInput> = {}` (attribute: false) — grammar definitions this
+  instance can highlight, e.g. `{ json: jsonGrammar }` (import from `shiki/langs/<name>.mjs`). Empty
+  (the default) never highlights at all — every `language` renders the plain-text fallback.
+
+**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.
+Identical behavior to `<lr-code-block>`'s own method.
+
+**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), `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`, `line-button` — identical set to `<lr-code-block>`.
+
+**Themeable custom properties:** identical to `<lr-code-block>` — `--lr-code-block-max-height`,
+`--lr-code-block-font`, plus the same shared tokens.
+
+**Optional peer deps:** `shiki` (specifically its `shiki/core`, `shiki/engine/oniguruma`,
+`shiki/wasm`, and `shiki/themes/github-{light,dark}.mjs` subpaths — never `shiki`'s main entry point,
+which is what carries the ~200-language table this component exists to avoid). Building the
+fine-grained highlighter is cached per `languages` object identity (a `WeakMap`), so passing the same
+module-level `languages` constant on every render builds it only once.
+
+```html
+<script type="module">
+  import jsonGrammar from 'shiki/langs/json.mjs';
+</script>
+<lr-code-block-core
+  language="json"
+  .languages=${{ json: jsonGrammar }}
+  .code=${'{"ok": true}'}
+></lr-code-block-core>
+```
+
+**Known gotchas:**
+- there is no default highlighter and no dynamic-import fallback table — a `language` you haven't
+  added to `languages` will never highlight, no matter how common that language is elsewhere. Reach
+  for `<lr-code-block>` instead if you need to support an open-ended set of languages without
+  pre-declaring each one.
+- `languages` is keyed by object identity for caching purposes — pass a stable, module-level constant
+  (not a fresh object literal per render), or every render rebuilds its own fine-grained highlighter.
+
+---

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

@@ -0,0 +1,146 @@
+<!-- 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), 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`.
+
+**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.
+
+---