@aceshooting/lyra-ui 5.0.0 → 5.2.0

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

@@ -0,0 +1,59 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/retrieval.md — do not edit this file. -->
+
+# `lr-community-card`
+
+- **Import** `import '@aceshooting/lyra-ui/components/retrieval/community-card/community-card.js';` (registers the tag; side-effect import)
+- **Class** `LyraCommunityCard`, also available unregistered from `@aceshooting/lyra-ui/components/retrieval/community-card/community-card.class.js`
+- **Family** `components/retrieval/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-community-card`
+
+A cluster/community summary card (GraphRAG community report): label, LLM summary excerpt, member
+count, member chips with overflow, and a drill-in action. Doesn't own community rendering on the
+graph or membership fetching — `lr-drill` asks the host to load members/subgraph.
+
+**Properties:**
+- `community: LyraCommunity | null = null` (attribute: false) — `LyraCommunity { id: string; label:
+  string; summary?: string; memberCount?: number }`; `memberCount` is authoritative when it exceeds
+  `members.length`; `null` renders the empty state
+- `members: LyraEntity[] = []` (attribute: false) — rendered as chips, up to `maxMembers`
+- `maxMembers: number = 8` (attribute `max-members`) — remaining members collapse into a "+N"
+  overflow chip
+- `compact: boolean = false` (reflected) — omits the summary excerpt and member chips
+- `appearance: 'card' | 'plain' = 'card'` (reflected) — visual chrome, mirroring `lr-card`'s
+  `appearance` vocabulary and this component's sibling `lr-entity-card`'s identical property.
+  `'card'` (the default) keeps the bordered, filled, padded box; `'plain'` removes the border,
+  background, and padding, so a card nested inside a container that already draws a border doesn't
+  double the frame.
+
+**Events:** `lr-drill` (`detail: { id }`, the drill button, header, or overflow chip — all three
+mean "show me this whole community"), `lr-entity-activate` (`detail: { id }`, a member chip was
+activated).
+
+**Slots:** `actions` — extra header actions alongside the built-in drill button.
+
+**CSS parts:** `base`, `header`, `title` (`role="heading" aria-level="3"` wrapping a `<button>`),
+`member-count`, `summary` (omitted in `compact`), `members` (omitted in `compact`), `member`,
+`overflow` (the "+N" chip button), `drill-button`, `actions`, `empty` (shown when `community` is
+`null`).
+
+**Themeable custom properties:** shared tokens only.
+
+**Optional peer deps:** none.
+
+```html
+<lr-community-card></lr-community-card>
+<script>
+  document.querySelector('lr-community-card').community = { id: 'c1', label: 'Early computing pioneers', summary: 'A cluster of 19th-century mathematicians and engineers.', memberCount: 12 };
+</script>
+```
+
+**Known gotchas:**
+- `memberCount` (not `members.length`) is the authoritative displayed count whenever it's larger —
+  useful when the host sends only a preview slice of members alongside the real total.
+
+---

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

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

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

@@ -0,0 +1,73 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/agent-tools.md — do not edit this file. -->
+
+# `lr-confirm-bar`
+
+- **Import** `import '@aceshooting/lyra-ui/components/agent-tools/confirm-bar/confirm-bar.js';` (registers the tag; side-effect import)
+- **Class** `LyraConfirmBar`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/confirm-bar/confirm-bar.class.js`
+- **Family** `components/agent-tools/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-confirm-bar`
+
+An inline, non-modal approve/deny block for one proposed action — the in-flow sibling of
+`lr-tool-approval-dialog` for confirmations that should sit in the transcript instead of hijacking
+focus. Same `lr-approve`/`lr-deny` event shapes as the dialog, and the same
+`toolApprovalHeading`/`toolApprovalArgsLabel`/`deny`/`approve` localization keys, so the two always
+translate in lockstep. Non-modal by contract: no focus trap, no scroll lock, no Escape/backdrop
+semantics, and it never steals focus when it appears in the transcript. DOM and tab order put Deny
+before Approve. On activation, focus moves synchronously to `[part="status"]` (an always-rendered,
+`tabindex="-1"` element) before the Deny/Approve buttons unmount.
+
+**Properties:** `toolName: string = ''` (attribute `tool-name`) — drives the default heading through
+the existing `toolApprovalHeading`/`toolApprovalGenericTool` dialog keys. `heading: string = ''` —
+free-form heading override for non-tool proposals; wins over `toolName`. `args: unknown = undefined`
+(attribute: false) — shown read-only inside a collapsed `lr-details` + `lr-json-viewer` when
+defined. `decision: 'approved' | 'denied' | null = null` (reflected) — decided state, set by the
+component on activation and host-writable (an externally-resolved decision renders identically but
+emits nothing). `tone: 'neutral' | 'danger' = 'neutral'` (reflected). `compact: boolean = false`
+(reflected) — collapses the bar from a full card (bordered, padded, `display: block` surface) to a
+single inline row with no chrome of its own, for a confirmation that has to live inside an existing
+container: a table cell, a card's action row, a toolbar. The host becomes `inline-flex`, and the
+narrow-allocation `@container` treatment is switched off — a compact bar is *expected* to be narrow,
+so stretching the buttons to fill would be exactly wrong. Re-chrome it through the
+`--lr-confirm-bar-compact-*` properties below. Everything else is unchanged: the event shapes, the
+focus-to-`[part="status"]`-before-unmount contract, and `role="group"` with its heading label.
+
+**Slots:** default — supplementary body content between the heading and the actions (e.g. a
+`lr-diff-view`). `footer` — extra content at the start of the action row.
+
+**Events:** `lr-approve` (`detail: { args }` — the `args` prop as-is, identical shape to
+`lr-tool-approval-dialog`), `lr-deny` (no detail, identical to the dialog).
+
+**CSS parts:** `base` (`role="group"`), `heading`/`tool-name`, `body`, `args` (the
+details/json-viewer wrapper, only rendered when `args` is defined), `footer`, `deny-button`,
+`approve-button` (named identically to the dialog's parts), `status` (the decided-state text, always
+present in the DOM as a focus landing spot).
+
+**Themeable custom properties:** the `compact` presentation is deliberately chrome-less by default
+and re-chromed entirely through five properties, all scoped to `[part="base"]` while `compact`:
+`--lr-confirm-bar-compact-padding` (default `0`, any padding shorthand),
+`--lr-confirm-bar-compact-gap` (default `var(--lr-space-s)`, the gap between the row's items),
+`--lr-confirm-bar-compact-border` (default `none`, any `border` shorthand),
+`--lr-confirm-bar-compact-background` (default `transparent`) and
+`--lr-confirm-bar-compact-radius` (default `0` — only visible once the border or background is set).
+They are inline `var()` fallbacks at their point of use rather than `:host` declarations, so any of
+them can be set on the element *or on any ancestor*, which is what makes "give every compact confirm
+bar in this panel a hairline border" a one-rule change on the panel.
+
+**Known gotchas:**
+- `[part="status"]` is always rendered and must never be given `display: none`. Deciding moves focus
+  to it synchronously, before the Deny/Approve buttons unmount, so hiding it would drop focus to
+  `<body>`. The shipped `:empty` rule on it has never matched, and that is load-bearing.
+- `[part="deny-button"]` and `[part="approve-button"]` are raw `<button>` elements, not composed
+  `lr-button`s, so `--lr-button-*` theming does not reach them. Style them through their parts.
+
+```html
+<lr-tool-call-chip status="pending"></lr-tool-call-chip>
+<lr-confirm-bar tool-name="run_shell" .args=${args}
+  @lr-approve=${(e) => run(e.detail.args)} @lr-deny=${() => cancel()}
+></lr-confirm-bar>
+```

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

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

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

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

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

@@ -0,0 +1,92 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/data.md — do not edit this file. -->
+
+# `lr-context-meter`
+
+- **Import** `import '@aceshooting/lyra-ui/components/data/context-meter/context-meter.js';` (registers the tag; side-effect import)
+- **Class** `LyraContextMeter`, also available unregistered from `@aceshooting/lyra-ui/components/data/context-meter/context-meter.class.js`
+- **Family** `components/data/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-context-meter`
+
+A segmented occupancy meter (bar or ring) for showing how a fixed capacity — a model's context
+window, a token budget, any consumable quota — is divided across labeled categories. First-party
+invention (no Web Awesome equivalent). Pure data visualization: it renders `segments`/`total` exactly
+as given and never computes token counts, costs, or any other domain-specific estimate itself — the
+one exception is the plain arithmetic sum of segment values used to build the accessible "X of Y
+used" summary.
+
+**Properties:**
+- `segments: ContextMeterSegment[] = []` (attribute: false, JS-only) — `{ label: string; value:
+  number; tone?: 'brand' | 'success' | 'warning' | 'danger' | 'neutral'; color?: string }[]`. `value` is an *absolute*
+  quantity measured against `total`, never a pre-computed percentage.
+  `color`, when supplied, is a sanitized arbitrary CSS color that takes precedence over `tone`.
+- `total: number = 0` — the full capacity segments are measured against (e.g. a model's context
+  window size).
+- `variant: 'ring' | 'bar' = 'bar'` (reflected)
+- `label: string = ''` — overall accessible caption, e.g. `"128K context window"`. Also rendered
+  visually (`[part="label"]`) when set.
+
+Accessible summaries, segment tooltips, and ring titles format quantities using `effectiveLocale`.
+A host `aria-label` overrides the generated meter summary and is preserved across reactive updates.
+
+**Events:** none.
+
+**Slots:** none.
+
+**CSS parts:** `base` (a `<div>` for `bar`, an `<svg>` for `ring`), `track` (the unfilled/empty
+capacity), `segment` (one occupied segment — carries `data-tone` and, for custom colors,
+`--lr-context-meter-segment-color`), `label`
+
+**Themeable custom properties:** `--lr-context-meter-segment-color` is set per segment when its
+`color` field is supplied; otherwise the component consumes shared tokens
+`--lr-space-xs`, `--lr-color-text-quiet`, `--lr-font`, `--lr-radius`, `--lr-color-border`,
+`--lr-color-surface` (the bar variant's inter-segment seam), `--lr-color-brand`,
+`--lr-color-success`, `--lr-color-warning`, `--lr-color-danger`, `--lr-transition-base`.
+
+**Optional peer deps:** none.
+
+```html
+<lr-context-meter
+  label="128K context window"
+  total="128000"
+  .segments=${[
+    { label: 'System prompt', value: 2200, tone: 'neutral' },
+    { label: 'Conversation history', value: 61000, tone: 'brand' },
+    { label: 'Retrieved context', value: 30800, tone: 'warning' },
+  ]}
+></lr-context-meter>
+
+<lr-context-meter variant="ring" total="128000" .segments=${segments}></lr-context-meter>
+```
+
+`role="img"` and a computed `aria-label` are set imperatively on the *host* element itself in
+`willUpdate` (mirroring `lr-gauge`'s "meter" role convention) — every internal node (`track`,
+`segment`, the ring's `<svg>`, `label`) is `aria-hidden`, so a screen reader gets one meaningful
+summary string instead of the raw markup. That summary's "used" figure is the sum of
+`segments[].value`, clamped to `total` whenever `total > 0` so the announced text can never claim
+more than 100% used (e.g. `segments` summing to `150000` against `total="128000"` still announces
+`"128,000 of 128,000 used"`) — matching what the *visual* meter shows, since each segment's ratio is
+independently clamped so the running cumulative fill across all segments can never exceed 100% of the
+bar/ring either: an over-`total` `segments` array renders as a fully (not over-) filled meter, with
+later segments truncated or squeezed to zero width/arc-length as the budget runs out. `total <= 0`
+(or non-finite) renders zero segments — an empty track/ring — and the announced summary falls back to
+just `"{used} used"` with no `"of {total}"` clause, regardless of what's in `segments`. Ring geometry
+(a 40-radius circle, 12px stroke, centered at 50,50) intentionally matches `lr-gauge`'s own radial
+numbers, so the two circular-meter components in the library share one visual scale.
+
+**Known gotchas:**
+- The ring variant's per-segment `<title>` and the bar variant's per-segment `title=` attribute are
+  native mouse-hover tooltips only — they sit inside `aria-hidden` markup, so screen readers never
+  read them; only the host's own `role="img"`/`aria-label` carries accessible information.
+- `variant="ring"` fixes the host at `8em × 8em` (`:host([variant='ring'])`) — the bar variant's
+  `inline-size: 100%` does not apply in ring mode; resize it via `font-size` or an explicit
+  width/height override on the host instead.
+- Segment order is significant for the ring's cumulative `stroke-dashoffset` — later entries in
+  `segments` render further around the circle (starting at 12 o'clock, going clockwise); there's no
+  independent sort/z-order control.
+
+---

package/llms/components/lr-control-group.md

@@ -0,0 +1,46 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/layout.md — do not edit this file. -->
+
+# `lr-control-group`
+
+- **Import** `import '@aceshooting/lyra-ui/components/layout/control-group/control-group.js';` (registers the tag; side-effect import)
+- **Class** `LyraControlGroup`, also available unregistered from `@aceshooting/lyra-ui/components/layout/control-group/control-group.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-control-group`
+
+Responsive semantic grouping for mixed controls and actions. It keeps slotted children in a
+wrapping inline-flex row, centers children with different intrinsic heights, and switches to a
+full-width allocation in narrow containers. Use it for dashboard toolbars that combine segmented
+controls, selects, buttons, and other interactive elements.
+
+**Properties:**
+- `label: string = ''` — accessible name for the internal `role="group"`; when empty, a host
+  `aria-label` is forwarded as a fallback.
+
+**Events:** none.
+
+**Slots:** default — controls, buttons, or other action content.
+
+**CSS parts:** `base` — the internal `role="group"` wrapper.
+
+**Themeable custom properties:** `--lr-control-group-gap` (default `var(--lr-space-xs)`) — gap
+between grouped controls; shared spacing and layout tokens apply as well.
+
+```html
+<lr-control-group label="Chart controls">
+  <lr-segmented></lr-segmented>
+  <lr-select></lr-select>
+  <lr-button>Export</lr-button>
+</lr-control-group>
+```
+
+**Known gotchas:**
+- This is a layout and semantics primitive; it does not coordinate child values or emit a group
+  change event.
+- Children wrap according to the group's own allocated inline size, not the viewport width.
+
+---

package/llms/components/lr-conversation-item.md

@@ -0,0 +1,158 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/conversation.md — do not edit this file. -->
+
+# `lr-conversation-item`
+
+- **Import** `import '@aceshooting/lyra-ui/components/conversation/conversation-item/conversation-item.js';` (registers the tag; side-effect import)
+- **Class** `LyraConversationItem`, also available unregistered from `@aceshooting/lyra-ui/components/conversation/conversation-item/conversation-item.class.js`
+- **Family** `components/conversation/` — 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-conversation-item`
+
+A selectable row representing one chat session in a history sidebar list. Usable standalone or as the
+`renderItem()` payload of `<lr-virtual-list>`; has no dependency on that (or any) other component.
+First-party invention (no Web Awesome equivalent).
+
+**Properties:**
+- `title: string = ''` — the session's display title. Falls back to "Untitled conversation" when empty
+  (display only — the property itself is never mutated by that fallback).
+- `excerpt: string = ''` — a short preview snippet of the last message. Omit for no excerpt line.
+  Ignored entirely once the `excerpt` slot has assigned content.
+- `timestamp?: Date | string` (attribute: false) — accepts a `Date` or anything `new Date()` can parse
+  (e.g. an ISO 8601 string); invalid input is treated as unset (no `<time>` rendered).
+- `formatTimestamp?: (date: Date) => string` (attribute: false) — overrides the default absolute-time
+  rendering (clock time for same-day timestamps, otherwise a calendar date). Not a fuzzy "2 hours ago"
+  relative string — bucketed relative grouping is a list-level concern, not this row's job.
+- `active: boolean = false` (reflected) — whether this is the currently-selected/open session; drives
+  the brand-quiet background treatment.
+- `editable: boolean = true` (reflected) — whether inline-rename is available at all. When `false`, the
+  rename button never renders and the row can never enter its editing state; flipping it to `false`
+  while a rename is already in progress cancels that edit (discards the draft, like Escape) rather
+  than leaving it stranded and still committable.
+- `compact: boolean = false` (reflected) — tighter row padding and gaps, for the dense history
+  sidebars these rows usually render in (same convention as `lr-empty`'s `compact`). Tightens
+  `[part='base']`'s padding to `var(--lr-space-xs) var(--lr-space-s)` and its gap to
+  `var(--lr-space-2xs)`, and collapses `[part='content']`'s inter-line gap to `0`. Deliberately
+  changes nothing else: it does **not** shrink `[part='rename-button']` below the shared
+  `--lr-icon-button-size` target floor, hide the excerpt, or reduce the excerpt/timestamp font
+  sizes — so a row carrying a rename button or slotted `actions` still floors at roughly that icon
+  size plus the compact padding, while a row with `editable=false` and no actions collapses much
+  further.
+- `spellcheck: boolean = true` — forwarded to the in-place rename `<input>`; `spellcheck="false"` is
+  parsed as false (not Lit's default boolean-attribute behavior)
+- `autocapitalize: string = ''` — forwarded to the in-place rename `<input>`; empty omits the attribute
+- `autoCorrect: string = ''` (attribute `autocorrect`) — forwarded to the in-place rename `<input>`
+  (Safari/WebKit-specific); empty omits the attribute. Named `autoCorrect` to avoid
+  `HTMLElement.autocorrect`'s incompatible DOM typing.
+
+**Events:** `lr-select` (no detail payload — identify the row via the platform `id` attribute on the
+event's `target`/`currentTarget`, the same convention `<lr-attachment-chip>` uses; fires on a click on
+`[part="option"]` outside the rename button/`actions` slot, or Enter/Space while it's focused, only
+while not currently renaming), `lr-rename` (`detail: { title: string }` — an in-place rename was
+committed via Enter or blur-while-editing; does not mutate `title` itself, this is a controlled
+component — not fired when the trimmed draft is empty or unchanged from the original `title`, treated
+as an implicit cancel), `blur` (no detail — re-dispatched from the in-place rename `<input>`'s own
+`blur`, bubbling and composed unlike the native event), `focus` (no detail — re-dispatched from the
+in-place rename `<input>`'s own `focus`, for the same reason as `blur`)
+
+**Slots:**
+- `actions` — overflow/icon-button controls rendered at the trailing edge of the row (e.g. a
+  pin/delete control); only visually shown once it actually has assigned elements. The only slot that
+  may hold focusable content.
+- `leading` — non-interactive leading content (avatar, purpose icon, status dot), rendered inside the
+  selectable region before the title/excerpt content.
+- `content` — replaces the built-in title + excerpt + meta content area with host-supplied
+  non-interactive row content.
+- `excerpt` — full override of the excerpt presentation (e.g. a search-hit snippet with `<mark>`);
+  wins over the `excerpt` property whenever it has assigned content.
+- `meta` — small, non-focusable structured fields below the title/excerpt (a day label, cost, request
+  count); entirely app-supplied, this component computes none of it.
+
+`leading`/`content`/`excerpt`/`meta` must all stay non-focusable — see the `role="button"` note below.
+
+**CSS parts:** `base`, `option`, `content`, `title`, `title-input`, `rename-button`, `excerpt`,
+`timestamp`, `actions`
+
+**Themeable custom properties:** `--lr-conversation-item-active-bg` (default
+`var(--lr-color-brand-quiet)`) — the row's background while `active`. `--lr-conversation-item-active-color`
+(default `var(--lr-color-text)`) — the text color of `[part='excerpt']` and `[part='timestamp']`
+while `active`. Both are declared as inline `var()` fallbacks at the point of use and never on
+`:host`, so either can be set on the element *or on any ancestor* (a thread-list wrapper, a page
+theme layer); `::part(base)[active]` is not valid CSS — Shadow Parts forbids an attribute selector
+after `::part()` — so the only previous lever was overriding the library-wide `--lr-color-brand-quiet`
+token and repainting everything else reading it. Unset, each falls back to exactly the token its rule
+used before.
+
+**These two are a contrast-sensitive pair — override them together, never one alone.** The
+`-active-color` hook exists precisely because the quiet text tone only reaches about 4.25:1 against
+the default active background; keep any override at 4.5:1 or better against it. And note that
+`[part='title']` is *not* restyled by the pair — it keeps `--lr-color-text` regardless — so a dark
+custom active background needs its own title color set alongside them, or the title drops below
+contrast while the excerpt stays legible.
+
+`--lr-conversation-item-compact-padding` (default `var(--lr-space-xs) var(--lr-space-s)`) —
+`[part='base']`'s padding while `compact`. `--lr-conversation-item-compact-gap` (default
+`var(--lr-space-2xs)`) — `[part='base']`'s gap while `compact`. Like the active-state pair, both are
+inline `var()` fallbacks at the point of use and never declared on `:host`, so a surrounding list can
+retune every row at once from an ancestor. `[part='content']`'s gap collapses to a flat `0` under
+`compact` with no hatch of its own — there is no smaller step left to retune to. `:host([compact])
+[part='base']` is ordered *before* `:host([active]) [part='base']` (equal specificity), so a row that
+is both compact and active keeps the active background and the promoted excerpt/timestamp contrast.
+
+Plus shared tokens — `--lr-space-xs/-s/-m`, `--lr-radius`,
+`--lr-transition-fast`, `--lr-color-text/-text-quiet/-brand/-brand-quiet/-surface`,
+`--lr-focus-ring-width/-color/-offset`, `--lr-icon-button-size`.
+
+**Optional peer deps:** none.
+
+```html
+<lr-conversation-item
+  id="sess_123"
+  title="Q3 roadmap planning"
+  excerpt="Let's revisit the timeline for the launch…"
+  .timestamp=${session.updatedAt}
+  ?active=${session.id === currentSessionId}
+  @lr-select=${(e) => openSession(e.currentTarget.id)}
+  @lr-rename=${(e) => renameSession(e.currentTarget.id, e.detail.title)}
+>
+  <button slot="actions" aria-label="Delete conversation">✕</button>
+</lr-conversation-item>
+```
+
+`role="button"` (not `"option"`) lives on `[part="option"]` — despite the part name — so the row has
+valid semantics both standalone and inside a larger history-list layout: it activates one current
+session rather than being a listbox option, so it requires no particular owner role. Selection is
+conveyed via `aria-current="true"` while `active`, not `aria-selected`. Because `role="button"`
+forbids focusable descendants (axe-core's `nested-interactive` rule), the rename button and the
+`actions` slot are rendered as DOM *siblings* of `[part="option"]` inside `[part="base"]`, not nested
+inside it — the same constraint the in-place rename `<input>` runs into one level deeper, which is
+why `[part="option"]` sheds its `role`/`tabindex`/`aria-current`/`aria-label` entirely for the
+duration of an edit rather than just visually swapping content (a row mid-edit *is* a text field).
+
+**Known gotchas:**
+- `lr-select` carries no detail payload at all — read the session id off the event's own `target`/
+  `currentTarget`, not a `detail` field.
+- Renaming is a controlled interaction: committing `lr-rename` never updates `title` locally: the
+  consumer must apply the new title once it's actually persisted.
+- An empty or unchanged (post-trim) rename draft is treated as an implicit cancel — no `lr-rename`
+  fires, and the row silently reverts to showing `title`.
+- Rename is triggered only by the dedicated pencil-icon button, never a double-click on the title —
+  double-click has no keyboard/screen-reader equivalent and would also swallow the row's own
+  single-click `lr-select`.
+- While renaming, `[part="option"]` has no `role`/`tabindex`/`aria-current`/`aria-label` at all — a
+  screen reader briefly stops announcing it as a button for the duration of the edit.
+- The part is named `option` for historical reasons but carries `role="button"`; don't write CSS or
+  ARIA assumptions that expect a listbox option.
+- Setting `editable = false` mid-rename silently discards the in-progress draft (no `lr-rename`
+  fires) — a consumer toggling `editable` off (e.g. in response to some other row entering rename
+  mode) should not expect the previous edit to be committed first.
+- `compact` is a spacing knob only — it never lowers the rename button's `--lr-icon-button-size`
+  floor. A compact row that still shows a rename button (or slotted `actions` at the same floor)
+  therefore bottoms out at roughly that icon size plus the compact padding, not at the text height.
+  Lowering `--lr-icon-button-size` at an ancestor is the explicit, informed opt-out of the
+  target-size floor; a density flag deliberately won't do it silently on your behalf.
+
+---

package/llms/components/lr-copy-button.md

@@ -0,0 +1,52 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/utility.md — do not edit this file. -->
+
+# `lr-copy-button`
+
+- **Import** `import '@aceshooting/lyra-ui/components/utility/copy-button/copy-button.js';` (registers the tag; side-effect import)
+- **Class** `LyraCopyButton`, also available unregistered from `@aceshooting/lyra-ui/components/utility/copy-button/copy-button.class.js`
+- **Family** `components/utility/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-copy-button`
+
+A standalone icon-only copy-to-clipboard button for a plain text `value` — swaps its icon to a
+checkmark for ~1.5s on activation. Takes no positioning opinion of its own; a consumer
+wraps/positions the host element (e.g. absolutely positioned in the corner of a `wa-textarea` or a
+read-only output field). Unlike `lr-code-block`'s or `lr-json-viewer`'s own built-in copy
+buttons, this has no code/JSON content model to adopt just to reuse the copy affordance.
+
+**Properties:**
+- `value: string = ''` — the plain text to copy.
+- `accessibleLabel: string | null = null` (attribute `aria-label`) — overrides the localized
+  Copy/Copied accessible name without changing the icon
+- `disabled: boolean = false` (reflected)
+- `feedbackDuration: number = 1500` (attribute `feedback-duration`) — milliseconds before the
+  copied checkmark returns to the copy icon; finite values are clamped at zero
+
+**Methods:** `focus(options?)` and `blur()` forward to the native button.
+
+**Events:** `lr-copy` (`detail: { text: string }`) — fires on activation, always with the current
+`value`, regardless of whether the OS clipboard write actually succeeded (same convention as
+`lr-code-block`'s/`lr-json-viewer`'s own copy buttons).
+
+**Slots:** none.
+
+**CSS parts:** `base` — the button itself.
+
+**Themeable custom properties:** shared tokens only.
+
+**Optional peer deps:** none.
+
+```html
+<lr-copy-button value="npm install @aceshooting/lyra-ui"></lr-copy-button>
+```
+
+**Known gotchas:**
+- best-effort clipboard write: `navigator.clipboard` is absent in insecure contexts/older browsers,
+  and some engines throw synchronously rather than rejecting — either way `lr-copy` still fires
+  with the intended text so a consumer can always show its own confirmation/fallback UI.
+
+---