@aceshooting/lyra-ui 5.0.0 → 5.2.0

package/llms/components/lr-chip.md

@@ -0,0 +1,170 @@
+<!-- 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`), the height pair `--lr-chip-min-height` / `--lr-chip-height` (below),
+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`).
+
+**Chip height — a floor and an exact cap:**
+
+- `--lr-chip-min-height` (default `--lr-size-1-5rem`) floors an **interactive** chip only — one in
+  toggle mode or with `removable` set. `2xs`/`xs`/`s`/`m` all share that `1.5rem` value because it
+  is the 24px WCAG 2.2 SC 2.5.8 target minimum and an interactive chip must never shrink below it;
+  `l` and `xl` raise it to their own taller floors. A passive display chip takes no floor from
+  this at all, and every default sits below the chip's own content-driven height, so the floor is
+  invisible until you raise it.
+- `--lr-chip-height` pins an **exact** height on `[part='base']` — interactive and passive chips
+  alike — so a row of chips can line up with a sibling control of a known height. It is
+  **undeclared by default**, which is what keeps the per-tier floor alive: `auto` is a valid
+  declared value that would win over the `var()` fallback arm and make `--lr-chip-min-height` dead
+  code, so never set it to `auto` — remove the declaration instead. Because the component never
+  declares it, it can be set inline, from an ancestor, or from an outer-tree rule.
+  **A value below 24px is for non-interactive display chips only**; pinning an interactive chip
+  that short breaks its tap target.
+
+**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,94 @@
+<!-- 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` (one chunk row; carries `role="listitem"` only
+below `virtualize-at` — while virtualized the surrounding `lr-virtual-list` row supplies that role
+instead), `chunk-current` (additional part on the row matching `activeId`), `score` (visible
+percent text), `score-current` (additional part on the current row's score line), `score-bar`
+(`aria-hidden` track), `score-fill` (tone-mapped fill), `score-fill-success` /
+`score-fill-warning` / `score-fill-danger` (additional part on the fill, one per scoring tier),
+`open-button`, `title` (the `<span>` inside `open-button` carrying the visible title text), `text`
+(omitted when `compact`), `text-clamped` (additional part on a `text` preview that is still
+collapsed; dropped once expanded), `toggle` ("Show more"/"Show less", omitted when `compact`),
+`empty` (shown when `chunks` is empty).
+
+Every row-level part is reachable through `::part()` in both rendering paths: above
+`virtualize-at` the row lives in the internal `lr-virtual-list`'s shadow root and its parts are
+re-exported from there under the same names. Row *state* is exposed as an additional part name
+rather than as an attribute on the part, because Shadow Parts forbids an attribute selector after
+`::part()` — `::part(chunk)[aria-current='true']` is invalid CSS. The equivalent attributes
+(`aria-current`, `data-tone`, `data-clamped`) are still present on the elements. A state part is a
+second token in the same `part` attribute, so a `[part~="…"]` (not `[part="…"]`) selector is the
+one that matches inside a tree.
+
+**Themeable custom properties:** `--lr-chunk-inspector-current-bg` (default
+`var(--lr-color-brand-quiet)`) — the background of the chunk matching `activeId`.
+`--lr-chunk-inspector-current-color` (default `var(--lr-color-text)`) — the text color of that
+chunk's `score` line (`::part(score-current)`). Both are inline `var()` fallbacks at the point of
+use rather than `:host` declarations, so either can be set on the element *or on any ancestor*:
+`::part(chunk)[data-active]` is invalid CSS — Shadow Parts forbids an attribute selector after
+`::part()` — which is why the current-chunk state is also published as its own part name
+(`chunk-current`, `score-current`); either the custom properties or `::part(chunk-current)` will
+retint it.
+
+**They are a contrast-sensitive pair — override them together, never one alone.** The `-current-color`
+hook exists precisely because the quiet token it replaces only reaches about 4.24:1 against the
+current background; keep any override at 4.5:1 or better against `--lr-chunk-inspector-current-bg`.
+
+Plus shared tokens otherwise.
+
+**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,118 @@
+<!-- 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`, `--lr-code-block-tab-size` (default `2`, applied to `[part='pre']`),
+`--lr-code-block-active-line-outline-color` (default `var(--lr-color-brand)`), plus the same shared
+tokens. Both of the last two are inline `var()` fallbacks at the point of use rather than `:host`
+declarations, so a page-, container-, or theme-level value reaches them; see `<lr-code-block>` above
+for the full rationale, including why `<lr-markdown>`/`<lr-markdown-core>` must declare the tab-size
+fallback separately.
+
+**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.
+
+---