@aceshooting/lyra-ui 5.0.0 → 5.2.0

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

@@ -0,0 +1,70 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/agent-tools.md — do not edit this file. -->
+
+# `lr-artifact-panel`
+
+- **Import** `import '@aceshooting/lyra-ui/components/agent-tools/artifact-panel/artifact-panel.js';` (registers the tag; side-effect import)
+- **Class** `LyraArtifactPanel`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/artifact-panel/artifact-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-artifact-panel`
+
+Shell around one agent-generated artifact: a title/kind header, a preview↔code toggle, version
+navigation with restore, a streaming indicator, and built-in copy/download actions. Renders none of
+the artifact itself — content is slotted. No content rendering of its own (slots own it), no
+dialog/dock chrome (compose `lr-dialog`/`lr-dock-panel`/`lr-split`), no version storage or
+diffing (host state; diffs via `lr-diff-view`), no code editing (`lr-code-editor`).
+
+**Properties:** `label: string = ''` — the artifact's title, shown in the header. `kind: string = ''`
+— a short kind label (e.g. `document`, `code`), shown as a badge next to `label`. `view: 'preview' |
+'code' = 'preview'` (reflected) — which slot is currently visible. `versions: ArtifactVersion[] = []`
+(attribute: false, each `{ id, label? }`) — the artifact's version history, oldest first; the last
+entry is the latest version. `activeVersionId: string | null = null` (attribute
+`active-version-id`) — the currently viewed version's id, or `null` for "the latest version."
+`streaming: boolean = false` (reflected) — whether the artifact is still being generated; sets
+`aria-busy` on the body and shows a text indicator (not animated, so it stays legible under reduced
+motion). `copyText: string = ''` (attribute `copy-text`) — the text copied to the clipboard by the
+copy button; empty hides the button. `downloadSrc: string = ''` (attribute `download-src`) — the
+download URL, sanitized through `safeMediaSrc()`; empty hides the button. `downloadName: string =
+''` (attribute `download-name`) — the suggested filename reported in the `lr-download` event
+detail.
+
+**Slots:** default — preview-view content (markdown/html-viewer/browser-frame/image). `code` —
+code-view content (typically a `lr-code-block`); the preview/code toggle only renders once this
+slot has assigned content. `actions` — extra header controls, rendered between the version
+navigation and the built-in copy/download buttons.
+
+**Events:** `lr-view-change` (`detail: { view }`), `lr-version-change` (`detail: { versionId }`,
+fired when the previous/next navigation moves to a different version), `lr-restore` (`detail: {
+versionId }`, fired by the restore-this-version button; mutates nothing itself), `lr-copy`
+(`detail: { text }`, after a best-effort clipboard write), `lr-download` (`detail: { filename,
+src? }`, with the sanitized download URL).
+
+**CSS parts:** `base`, `header`, `label`, `kind`, `view-toggle` (rendered only once the `code` slot
+has content), `view-button` (carries `data-view="preview"` or `data-view="code"`), `version-nav`
+(rendered only once `versions` is non-empty), `version-previous`, `version-previous-glyph` (the `‹`
+chevron inside `version-previous`, mirrored via `scaleX(-1)` under `:dir(rtl)`), `version-next`,
+`version-next-glyph` (the `›` chevron inside `version-next`, mirrored the same way), `version-position`
+(the "Version N of M" text), `restore-button` (rendered only while the active version isn't the
+latest), `actions`, `copy-button` (rendered only while `copyText` is non-empty), `download-button`
+(rendered only while `downloadSrc` is non-empty), `body`, `streaming-indicator` (rendered only while
+`streaming`).
+
+**Themeable custom properties:** `--lr-artifact-panel-view-active-bg` (default
+`var(--lr-color-brand-quiet)`) and `--lr-artifact-panel-view-active-color` (default
+`var(--lr-color-brand)`) — the background and text color of the pressed (active) preview/code toggle
+button. Both follow the state-scoped-property convention described under `lr-span-waterfall`: inline
+`var()` fallbacks rather than `:host` declarations, so either can be set on the element or on any
+ancestor. They exist because `::part(view-button)[aria-pressed='true']` is invalid CSS, leaving the
+library-wide brand tokens as the only prior lever.
+
+```html
+<lr-artifact-panel label="report.md" kind="document" .versions=${versions}
+  @lr-restore=${(e) => restoreVersion(e.detail.versionId)}>
+  <lr-markdown .content=${markdown}></lr-markdown>
+  <lr-code-block slot="code" language="markdown" .code=${markdown}></lr-code-block>
+</lr-artifact-panel>
+```

package/llms/components/lr-attachment-chip.md

@@ -0,0 +1,131 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/media.md — do not edit this file. -->
+
+# `lr-attachment-chip`
+
+- **Import** `import '@aceshooting/lyra-ui/components/media/attachment-chip/attachment-chip.js';` (registers the tag; side-effect import)
+- **Class** `LyraAttachmentChip`, also available unregistered from `@aceshooting/lyra-ui/components/media/attachment-chip/attachment-chip.class.js`
+- **Family** `components/media/` — 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-attachment-chip`
+
+A compact chip representing one file queued for (or already part of) a chat message — used in a
+composer's pre-send attachment tray or a sent message's attachments display. Two independent ways
+to populate it: set `file` to a real `File` (fresh from a picker/drop), from which `name`/`size`/
+`mime-type` and the image thumbnail are all auto-derived; or set the plain `name`/`size`/
+`mime-type`/`thumbnail-src` props instead, for reconstructing a chip from server-persisted
+attachment metadata after a page reload, when no real `File` object exists any more. `file` always
+wins when both are present. When a real `File` or `preview-src` is available, the chip also offers
+a localized preview action that opens `<lr-document-viewer>` using the same effective MIME type.
+
+**Properties:**
+- `file?: File` (attribute `false`, i.e. property-only) — when set, `name`/`size`/`mimeType`/the
+  image thumbnail are all derived from it, taking precedence over the independent props below
+- `name: string = ''` — filename, used only while `file` is unset
+- `size: number = 0` — file size in bytes, used only while `file` is unset
+- `mimeType: string = ''` (attribute `mime-type`) — used only while `file` is unset
+- `thumbnailSrc: string = ''` (attribute `thumbnail-src`) — thumbnail image URL, used only while
+  `file` is unset; rendered whenever present regardless of `mimeType` (no `file`-derived equivalent
+  exists for a non-image file)
+- `previewSrc: string = ''` (attribute `preview-src`) — source URL used for preview and download when
+  `file` is unset; a real `File` takes precedence and uses a temporary blob URL
+- `previewable: boolean = true` (reflected) — shows the preview action whenever a `file` or
+  `preview-src` is available
+- `status: AttachmentChipStatus = 'pending'` (reflected) — `'pending' | 'uploading' | 'error' |
+  'done'`; drives the accent tint and which of `progress`/`spinner`/`retry-button` renders
+- `progress: number = 0` — upload completion, 0-100; only meaningful while `status="uploading"`, a
+  value of `0` or `NaN` falls back to the indeterminate spinner
+- `removable: boolean = true` (reflected) — shows the remove (×) button
+- `compact: boolean = false` (reflected) — renders a smaller, borderless pill presentation instead of
+  the default bordered/chrome-heavy chip, e.g. for a composer's pending-attachment tray. `false` (the
+  default) is visually identical to the standard chip.
+- `thumbnailOnly: boolean = false` (reflected, attribute `thumbnail-only`) — when both this and
+  `compact` are set, hides `[part='meta']` (the filename/size text) entirely for an image-mime
+  attachment, leaving only the thumbnail. Has no effect for a non-image chip, or when `compact` is
+  unset. `false` (the default) reproduces the chip's exact existing output.
+- `removeLabel: string = 'Remove'` (attribute `remove-label`) — verb used in the remove button's
+  accessible name; the default routes through the complete localized `removeWithContext` template
+- `retryLabel: string = 'Retry'` (attribute `retry-label`) — verb used in the retry button's
+  accessible name; the default routes through the complete localized attachment template
+- `uploadingLabel: string = 'Uploading'` (attribute `uploading-label`) — verb used in the visible
+  uploading status; the untouched default uses complete localized messages for progress,
+  indeterminate state, and filename context so translators can reorder every value
+- `uploadFailedLabel: string = 'Upload failed'` (attribute `upload-failed-label`) — visible status
+  text shown for `status="error"`; override for i18n/locale
+- `untitledLabel: string = 'Untitled file'` (attribute `untitled-label`) — fallback filename and
+  tooltip when neither `file` nor `name` supplies a name
+
+The component identifies *which* attachment a `lr-remove`/`lr-retry` event is about via the
+platform's own `id` attribute/property rather than a second, differently-named prop. Set `id="..."`
+when you have a stable server-side attachment id; when unset and `file` is set, a stable id is
+derived from `` `${file.name}:${file.size}:${file.lastModified}` ``; when neither is available, a
+generated internal id is used as a last resort.
+
+**Events:** `lr-remove` (`detail: { id }`, only rendered while `removable`), `lr-retry`
+(`detail: { id }`, only rendered while `status="error"`), `lr-preview` (`detail: { id, name,
+mimeType, src }`, emitted when the preview action opens the document viewer)
+
+**Slots:** none.
+
+**CSS parts:** `base`, `thumbnail`, `meta`, `name`, `size`, `status-text`, `progress`,
+`progress-fill`, `spinner`, `retry-button`, `preview-button`, `remove-button`
+
+**Themeable custom properties:** `--lr-attachment-chip-accent` (default
+`var(--lr-color-text-quiet)`), `--lr-attachment-chip-bg` (default `var(--lr-color-surface)`),
+`--lr-attachment-chip-border` (default `var(--lr-color-border)`) — this trio is swapped per
+`status` (`uploading` → brand/brand-quiet/transparent, `error` → danger/danger-quiet/transparent,
+`done` → success/success-quiet/transparent); `--lr-attachment-chip-compact-thumbnail-size` (default
+`1.75rem`), `--lr-attachment-chip-compact-font-size` (default `var(--lr-font-size-xs)`),
+`--lr-attachment-chip-compact-gap` (default `0.25rem`) — govern the chip's thumbnail size, text
+size, and internal gap while `compact` is set; `--lr-attachment-chip-spinner-duration` (default
+`0.8s`) controls the indeterminate rotation and stops under reduced motion; plus shared tokens `--lr-space-xs`, `--lr-space-s`,
+`--lr-radius`, `--lr-color-text`, `--lr-color-danger`, `--lr-icon-button-size`,
+`--lr-transition-fast`, `--lr-transition-base`, `--lr-focus-ring-width`,
+`--lr-focus-ring-color`, `--lr-focus-ring-offset`.
+
+**Optional peer deps:** none.
+
+Also exported from the package root: `formatFileSize(bytes: number): string` — `512` → `"512 B"`
+(whole bytes never get a decimal), `2415919` → `"2.3 MB"` (every unit past bytes gets exactly one
+decimal place), and a negative or non-finite input (`NaN`, `Infinity`) returns `""` so an unknown
+size renders nothing instead of `"NaN B"`.
+
+```html
+<lr-attachment-chip name="report.pdf" size="245000" mime-type="application/pdf" status="done"></lr-attachment-chip>
+<lr-attachment-chip id="att-2" status="uploading" progress="42"></lr-attachment-chip>
+<script type="module">
+  import { formatFileSize } from '@aceshooting/lyra-ui';
+
+  const chip = document.createElement('lr-attachment-chip');
+  chip.file = pickedFile; // name/size/mime-type/thumbnail all derived from the File
+  chip.addEventListener('lr-remove', (e) => removeAttachment(e.detail.id));
+  chip.addEventListener('lr-retry', (e) => retryUpload(e.detail.id));
+  chip.addEventListener('lr-preview', (e) => console.log(e.detail));
+  console.log(formatFileSize(pickedFile.size));
+</script>
+```
+
+The image thumbnail for a real `File` is a lazily-created `URL.createObjectURL()` blob URL —
+created only from `render()`, i.e. only once a thumbnail is actually about to paint, never eagerly
+on `file` assignment — and revoked automatically once `file` changes to a different `File` (or to
+`undefined`) and on disconnect, so reassigning `file` several times before the next paint never
+leaks URLs that were created but never shown.
+
+**Known gotchas:**
+- `file` always wins over `name`/`size`/`mimeType` when both are set — assigning those props while
+  `file` is also set has no visible effect on the rendered chip.
+- A `0`-byte size and an unset size are indistinguishable (there's no separate flag for "genuinely
+  empty file"); the `size` part is hidden entirely rather than showing a literal `"0 B"`.
+- `progress` only renders as a numeric bar when `status="uploading"` **and** `progress` is finite
+  and `> 0`; otherwise it's either nothing (non-`uploading` status) or the indeterminate spinner
+  (`uploading` with no known progress).
+- `thumbnailSrc` is used whenever present regardless of `mimeType` — pass a URL that's already known
+  to be an image; there's no non-image fallback check for it the way there is for `file`.
+- `previewSrc` is used only when `file` is unset. A preview action is omitted when neither a real
+  `File` nor `preview-src` supplies a source. The viewer's footer omits its download link for unsafe
+  source schemes.
+
+---

package/llms/components/lr-attachment-trigger.md

@@ -0,0 +1,90 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/media.md — do not edit this file. -->
+
+# `lr-attachment-trigger`
+
+- **Import** `import '@aceshooting/lyra-ui/components/media/attachment-trigger/attachment-trigger.js';` (registers the tag; side-effect import)
+- **Class** `LyraAttachmentTrigger`, also available unregistered from `@aceshooting/lyra-ui/components/media/attachment-trigger/attachment-trigger.class.js`
+- **Family** `components/media/` — 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-attachment-trigger`
+
+A compact attach affordance designed for a chat composer's leading slot (see `lr-chat-composer`'s
+own `leading` slot, which this drops straight into, though it has no code dependency on it). First-
+party invention (no Web Awesome equivalent). Its shape adapts to how many attachment `capabilities`
+are configured: exactly one renders a single plain icon button; more than one renders a small
+anchored menu (composed from the already-landed `lr-menu`/`lr-menu-item`) listing each
+capability as a row.
+
+**Properties:**
+- `capabilities: AttachmentCapability[] = ['files']` (property only, no attribute) — which
+  capabilities to offer, in display order. `AttachmentCapability = 'files' | 'image' | 'camera' |
+  'audio'`; `FileBackedCapability = 'files' | 'image'` (the two that actually open the file
+  picker).
+- `accept: string = ''` — a native-file-input-style accept string (e.g. `'image/*'` or
+  `'.pdf,.docx'`), forwarded to the hidden file input for the `files`/`image` capabilities. `image`
+  defaults it to `'image/*'` unless this prop overrides it; `files` always uses it as-is (empty
+  means "any file type").
+- `multiple: boolean = true` (reflected) — forwarded to the hidden file input's own `multiple`
+  attribute.
+- `disabled: boolean = false` (reflected)
+- `triggerLabel?: string` (attribute `trigger-label`) — overrides the single-capability trigger
+  button's `aria-label`, which otherwise comes from `CAPABILITY_META[capability].triggerLabel` (e.g.
+  `'Attach files'`); only affects the single-capability button (`[part='trigger']`) — the
+  multi-capability menu's own trigger keeps its fixed `'Add attachment'` label regardless. Unset
+  (the default) keeps the built-in English default.
+- `triggerTitle?: string` (attribute `trigger-title`) — forwards a sighted-user hover tooltip to
+  both the single-capability and multi-capability trigger buttons
+
+**Events:** `lr-pick` (`detail: { capability: 'files' | 'image'; files: FileList }`) — fired once a
+file-backed capability's hidden input produces a real selection. The `FileList` is an independent
+snapshot (rehomed into a fresh `DataTransfer`), not a live reference to the input's own `.files` —
+see the gotcha below for why that distinction matters. `lr-camera-request` and `lr-audio-request`
+(both no detail — `detail` is `null`, not `undefined`, per the DOM spec's `CustomEventInit`
+default) — fired when the `camera` / `audio` capability is activated; this component implements no
+capture UI of its own, the host owns everything from here (there's no single right answer for
+`getUserMedia` vs. `<input capture>` vs. a native wrapper's own camera API; for `audio` the
+typical host response is opening `<lr-push-to-talk>` in an overlay, then handing the resulting
+blob to `<lr-attachment-chip>`). Internal `focus`/`blur` from the hidden input are re-emitted as
+host events.
+
+**Slots:** none — capabilities are configured entirely via the `capabilities` prop.
+
+**CSS parts:** `trigger` (the single-capability button, only rendered when
+`capabilities.length === 1`), `menu` (the `lr-menu` wrapper, only rendered when
+`capabilities.length > 1`), `menu-trigger` (the multi-capability button slotted into `lr-menu`'s own
+`trigger` slot, only rendered when `capabilities.length > 1`), `expand-icon` (the disclosure chevron
+inside the multi-capability trigger button, only rendered when `capabilities.length > 1`),
+`hidden-input` (the internal native `<input type="file">` that actually opens the OS file picker;
+hidden via CSS by default, exposed as a part only so a consumer can override that with
+`::part(hidden-input)` in the unlikely case their integration needs to).
+
+**Themeable custom properties:** shared tokens only — `--lr-space-xs`, `--lr-color-text`/
+`-text-quiet`, `--lr-icon-button-size`, `--lr-focus-ring-*`, `--lr-opacity-disabled`,
+`--lr-radius`, `--lr-transition-fast`.
+
+**Optional peer deps:** none.
+
+```html
+<lr-attachment-trigger .capabilities=${['files', 'image', 'camera']} accept=".pdf,.docx"
+  @lr-pick=${(e) => queueFiles(e.detail.capability, e.detail.files)}
+  @lr-camera-request=${openCameraFlow}
+></lr-attachment-trigger>
+```
+
+**Known gotchas:**
+- `HTMLInputElement.files` is a *live* view in most browsers — clearing `input.value` after reading
+  `.files` (needed so re-picking the exact same file still fires another `change` event next time)
+  mutates that exact `FileList` object back to empty in place, not just detaches a stale reference.
+  A consumer reading `lr-pick`'s `detail.files` even one microtask later (an `async` handler, a
+  queued upload) would otherwise observe an empty list — this component avoids that by rehoming the
+  selection into a fresh `DataTransfer` before emitting, but any other file-input-adjacent code
+  emitting `input.files` directly without that rehoming step has the same latent bug.
+- The `camera`/`audio` capabilities never touch the hidden `<input type="file">` at all — both are
+  scope-limited by design to firing `lr-camera-request`/`lr-audio-request` and nothing else. The
+  hidden input is only rendered when `capabilities` contains `files` or `image`.
+
+---

package/llms/components/lr-audio-visualizer.md

@@ -0,0 +1,43 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/conversation.md — do not edit this file. -->
+
+# `lr-audio-visualizer`
+
+- **Import** `import '@aceshooting/lyra-ui/components/conversation/audio-visualizer/audio-visualizer.js';` (registers the tag; side-effect import)
+- **Class** `LyraAudioVisualizer`, also available unregistered from `@aceshooting/lyra-ui/components/conversation/audio-visualizer/audio-visualizer.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-audio-visualizer`
+
+A presentational, canvas-drawn voice-activity visualization (bars or waveform) — the
+LiveKit-BarVisualizer counterpart for this library. Driven by a `MediaStream` (lazily wired to a
+WebAudio `AnalyserNode`), a numeric `level` for hosts that already compute levels (e.g.
+`<lr-push-to-talk>`'s `lr-level`), or `state` alone for an ambient animation when no real signal
+exists. A real signal (`stream` or `level`) always drives amplitude regardless of
+`prefers-reduced-motion`; only the signal-less ambient animation is throttled under reduced motion.
+
+**Properties:** `stream: MediaStream | null = null` (attribute: false) — a live capture stream, lazily
+wired to a WebAudio `AnalyserNode`; `level: number | null = null` — a pre-computed 0–1 amplitude for
+hosts that already have one (e.g. `lr-push-to-talk`'s `lr-level` detail); `state: 'idle' |
+'listening' | 'thinking' | 'speaking' = 'idle'` (reflected) — drives the signal-less ambient
+animation and per-state coloring; `variant: 'bars' | 'waveform' = 'bars'` (reflected); `barCount:
+number = 5` (attribute `bar-count`); `gain: number = 1` — multiplier applied to the resolved
+amplitude; `label: string = ''` — the host's accessible name.
+
+**Methods:** `refreshTheme()` re-reads themeable custom properties after a runtime theme change (the
+canvas resolves token values at paint time and cannot inherit `var()` directly).
+
+**Events:** none — purely presentational.
+
+**Slots:** none.
+
+**CSS parts:** `base` (the root wrapper) and `canvas` (the drawing surface, `aria-hidden`; the host
+itself carries `role="img"` and the accessible name).
+
+**Themeable custom properties:** `--lr-audio-visualizer-color` (default `--lr-color-brand` —
+active bar/waveform color), `--lr-audio-visualizer-quiet-color` (default
+`--lr-color-brand-quiet` — inactive/idle color), and `--lr-audio-visualizer-height` (default
+`var(--lr-size-3rem)` — the host's block size).

package/llms/components/lr-av-player.md

@@ -0,0 +1,86 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/media.md — do not edit this file. -->
+
+# `lr-av-player`
+
+- **Import** `import '@aceshooting/lyra-ui/components/media/av-player/av-player.js';` (registers the tag; side-effect import)
+- **Class** `LyraAvPlayer`, also available unregistered from `@aceshooting/lyra-ui/components/media/av-player/av-player.class.js`
+- **Family** `components/media/` — 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-av-player`
+
+An audio/video player built on a native `<audio>`/`<video>` element, plus a cue transcript synced to
+`currentTime`, `time-range` anchor/highlight support, an optional dependency-free waveform (peaks
+in, no in-component decoding), and playback-rate control. Owns recorded-media transcript sync —
+distinct from `<lr-transcript-feed>` (live captions for an in-progress voice session) and
+`<lr-playback>` (an index stepper, no media). Adopts `DocumentAnchorTarget` with
+`anchorKinds: ['time-range']` only — no text selection is bound. The transcript virtualizes through
+`<lr-virtual-list>` the same way `lr-pdf-viewer` virtualizes pages.
+
+**Properties:** `src: string = ''`, `name: string = ''`, `kind?: 'audio' | 'video'` (attribute:
+false auto-detection override), `mimeType: string = ''` (attribute `mime-type`), `poster: string =
+''`, `loop: boolean = false`, `muted: boolean = false`, `preload: 'none' | 'metadata' | 'auto' =
+'metadata'`, `playbackRate: number = 1` (attribute `playback-rate`, reflected), `rates: number[] =
+[0.75, 1, 1.25, 1.5, 2]` (attribute: false), `cues: LyraAvCue[] = []` (attribute: false), `peaks:
+number[] = []` (attribute: false), and `tracks: LyraAvTrack[] = []` (attribute: false).
+`LyraAvCue = { id, start, end?, text, speaker? }`; `LyraAvTrack = { src, kind: 'subtitles' |
+'captions' | 'descriptions', srclang, label, default? }`.
+
+**Methods:** `play()`, `pause()`, and `toggle()` proxy the native media element. `seek(seconds)`
+sets `currentTime` and forces an immediate `lr-time-change`. `search(query)` resolves the match
+count; `searchNext()`/`searchPrevious()` wrap; `clearSearch()` resets.
+
+**Events:** `lr-play`, `lr-pause`, `lr-load` (`detail: { duration, kind }`), `lr-time-change`
+(`detail: { currentTime }`, throttled to at most 4/s while playing plus one extra per `seek()`),
+`lr-rate-change` (`detail: { rate }`), `lr-cue-change` (`detail: { id }`, `id` is `null` when no
+cue is active), `lr-highlight-activate` (`detail: { id }`), `lr-anchor-result` (`detail: {
+found }`), `lr-search-change` (`detail: { query, matchCount, activeIndex }`), and
+`lr-render-error` (`detail: { error }`).
+
+**CSS parts:** `base`, `media` (the native `<audio>`/`<video>` element), `toolbar`, `rate-select`,
+`timeline` (click-to-seek and arrow-key seeking), `timeline-marker` (one per `time-range` highlight;
+`data-tone`, `data-active`), `transcript` (the `<lr-virtual-list>` itself), `cue` (`aria-current`,
+`data-match`, `data-active-match`), `cue-current` (added alongside `cue` on the row the playhead is
+inside), `cue-match` (added alongside `cue` on a row matching the current search query),
+`cue-active-match` (added alongside `cue`/`cue-match` on the row holding the current match),
+`cue-time`, `cue-speaker`, `cue-text`, and `error`.
+
+Every cue-level part above is rendered into the embedded `<lr-virtual-list>`'s own shadow root and
+forwarded back out through `exportparts`, so `lr-av-player::part(cue)` and friends work from a
+consumer stylesheet. The three cue states are separate part *names* rather than attribute selectors,
+because Shadow Parts forbids an attribute selector after `::part()` —
+`::part(cue)[aria-current='true']` is invalid CSS, so use `::part(cue-current)`. The `aria-current`
+and `data-*` attributes remain on each row for semantics and scripting.
+
+**Themeable custom properties:** `--lr-av-player-transcript-height` (default
+`var(--lr-size-16rem)` — block size of the transcript pane; forwarded to the embedded
+`<lr-virtual-list>`'s own `--lr-virtual-list-height`). `--lr-av-player-marker-active-color` (default
+`var(--lr-color-brand)`) — the outline of the `[part='timeline-marker']` matching
+`activeHighlightId`, leaving the per-tone marker fills alone. It is an inline `var()` fallback at
+the point of use rather than a `:host` declaration, so it can be set on the element or on any
+ancestor — `::part(timeline-marker)[data-active]` is invalid CSS (Shadow Parts forbids an attribute
+selector after `::part()`), so re-pointing the shared `--lr-color-brand` token was the only previous
+lever.
+
+Each `[part='timeline-marker']`'s own background is independently overridable per tone, the same
+inline-`var()`-fallback pattern as `--lr-av-player-marker-active-color` above:
+`--lr-av-player-marker-bg` (default `color-mix(in srgb, var(--lr-color-brand) 35%, transparent)`) —
+no (or an unrecognized) `data-tone`; `--lr-av-player-marker-success-bg` (default `color-mix(in srgb,
+var(--lr-color-success) 35%, transparent)`) — `data-tone="success"`;
+`--lr-av-player-marker-warning-bg` (default `color-mix(in srgb, var(--lr-color-warning) 35%,
+transparent)`) — `data-tone="warning"`; `--lr-av-player-marker-danger-bg` (default `color-mix(in
+srgb, var(--lr-color-danger) 35%, transparent)`) — `data-tone="danger"`; and
+`--lr-av-player-marker-neutral-bg` (default `color-mix(in srgb, var(--lr-color-text) 25%,
+transparent)`) — `data-tone="neutral"`. Each can be set on the element or on any ancestor without
+hijacking the shared `--lr-color-success`/`-warning`/`-danger`/`-brand`/`-text` tokens used
+elsewhere in the theme.
+
+Two further cue-state properties tint the transcript: `--lr-av-player-cue-current-bg` (default
+`var(--lr-color-brand-quiet)`) is the background of the `cue-current` row the playhead is inside,
+and `--lr-av-player-cue-active-match-color` (default `var(--lr-color-warning)`) is the outline of
+the `cue-active-match` row, leaving the other matches' dashed outline on the shared warning token.
+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.

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

@@ -0,0 +1,74 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/media.md — do not edit this file. -->
+
+# `lr-avatar-group`
+
+- **Import** `import '@aceshooting/lyra-ui/components/media/avatar-group/avatar-group.js';` (registers the tag; side-effect import)
+- **Class** `LyraAvatarGroup`, also available unregistered from `@aceshooting/lyra-ui/components/media/avatar-group/avatar-group.class.js`
+- **Family** `components/media/` — 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-avatar-group`
+
+Stacks slotted `<lr-avatar>` children into one overlapping row and, past `max`, collapses the
+excess into a localized "+N" badge. Composed over `<lr-avatar>` via plain light-DOM slotted content
+(no `.items` array); it does **not** import/register `<lr-avatar>` — the consumer does that.
+
+**Properties:**
+- `max?: number` — how many assigned children stay visible before the rest collapse behind the
+  badge. Unset (the default) means no limit. Any assigned value is sanitized to a finite,
+  non-negative integer. Flattened slot-forwarded children count the same as direct children.
+- `size: AvatarSize = 'md'` (reflected) — `'sm' | 'md' | 'lg'`, reused from `<lr-avatar>`.
+- `shape: AvatarShape = 'circle'` (reflected) — `'circle' | 'square'`.
+- `tone: AvatarTone = 'neutral'` (reflected) — `'neutral' | 'brand' | 'success' | 'warning' |
+  'danger'`; recolors the overflow badge only.
+- `label: string = ''` — the group's `role="group"` accessible name. A host-level `aria-label` wins
+  if both are set; with neither, no `aria-label` is rendered.
+
+**Events:** `lr-overflow-click` (`detail: { hiddenCount: number; hiddenAvatars: LyraAvatar[] }`) —
+the badge was activated by click or Enter/Space. Non-cancelable, purely informational: the
+component keeps rendering the same collapsed stack, and a host typically wires this to its own
+popover/dialog listing the hidden members. There is no `expanded` state and no `aria-expanded`.
+
+**Slots:** default slot — `<lr-avatar>` elements (any content works, but the avatar pairing is the
+intended usage). Children past `max` have their native `hidden` attribute set.
+
+**CSS parts:** `base` (the outer inline-flex container holding the slot and the badge),
+`overflow-badge` (the "+N" `<button>`; only rendered while `max` is actively overflowing).
+
+**Themeable custom properties:** `--lr-avatar-group-avatar-size` (default `var(--lr-size-2rem)`,
+swapped to `1.5rem`/`2.5rem` per `size`), `--lr-avatar-group-overlap` (default
+`var(--lr-size-neg-6px)`, swapped per `size`; a logical `margin-inline-start`, so it auto-mirrors
+under `dir="rtl"` — setting `0` or a positive length turns the stack into normal spacing),
+`--lr-avatar-group-ring-color` (default `var(--lr-color-surface)`),
+`--lr-avatar-group-ring-width` (default `var(--lr-border-width-medium)`),
+`--lr-avatar-group-badge-bg` (default `var(--lr-color-border)`, swapped per `tone`),
+`--lr-avatar-group-badge-color` (default `var(--lr-color-text)`, swapped per `tone`),
+`--lr-avatar-group-badge-font-size` (default `var(--lr-font-size-sm)`) — the font size of the "+N"
+badge label. `size` swaps it per tier (`var(--lr-font-size-xs)` at `sm`, `var(--lr-font-size-md)` at
+`lg`), matching `<lr-avatar>`'s own `--lr-avatar-font-size` scale so the badge and the avatars it
+caps read at the same optical weight; override it alongside `--lr-avatar-font-size` on the avatars
+themselves when tuning a custom tier.
+
+**Optional peer deps:** none.
+
+```html
+<lr-avatar-group max="3" label="Project members">
+  <lr-avatar initials="JS"></lr-avatar>
+  <lr-avatar initials="AM"></lr-avatar>
+  <lr-avatar initials="RT"></lr-avatar>
+  <lr-avatar initials="KL"></lr-avatar>
+</lr-avatar-group>
+```
+
+**Known gotchas:**
+- `size`/`shape`/`tone` do **not** cascade onto slotted avatars — they only drive this component's
+  own ring, overlap, and badge. Each `<lr-avatar>`'s own `--lr-avatar-size` lives in its own
+  shadow-scoped `:host` block and unconditionally overrides an inherited value, so set a matching
+  `size`/`shape` on both the group and every child.
+- the row never wraps (`flex-wrap` stays `nowrap`) — wrapping an overlapping stack breaks the
+  visual.
+- avatars are non-interactive, so there is no roving tabindex / arrow-key handling; the badge is the
+  only tab stop.

package/llms/components/lr-avatar.md

@@ -0,0 +1,73 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/media.md — do not edit this file. -->
+
+# `lr-avatar`
+
+- **Import** `import '@aceshooting/lyra-ui/components/media/avatar/avatar.js';` (registers the tag; side-effect import)
+- **Class** `LyraAvatar`, also available unregistered from `@aceshooting/lyra-ui/components/media/avatar/avatar.class.js`
+- **Family** `components/media/` — 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-avatar`
+
+A small, fixed-size identity marker: default-slotted icon/glyph content, an image, or a fallback of
+initials text — in that priority order, whichever is set takes over from the next. First-party
+invention (no Web Awesome equivalent) — purely presentational, with no built-in interactivity; wrap
+it in a `<button>`/`<lr-menu>` trigger for a user-menu affordance.
+
+**Properties:**
+- `initials: string = ''` — fallback text (typically 1-2 characters), shown whenever no slotted icon
+  and no image is set, or the image fails to load.
+- `src?: string` — image URL; takes priority over `initials` when set and loads successfully (but
+  never over slotted icon content), falling back to `initials` on a load error.
+- `alt: string = ''` — image alt text; set alongside `src` for accessibility, and also the source of
+  the accessible name for the icon-slot and initials cases (the glyph is `aria-hidden`, and the
+  initials text is hidden from AT once `alt` supplies a name, so `[part="base"]` carries
+  `role="img"` + that name instead).
+- host `aria-label` — overrides `alt` as the image/fallback accessible name without changing the
+  visible initials or image
+- `size: 'sm' | 'md' | 'lg' = 'md'` (reflected).
+- `shape: 'circle' | 'square' = 'circle'` (reflected).
+- `tone: 'neutral' | 'brand' | 'success' | 'warning' | 'danger' = 'neutral'` (reflected) — recolors
+  the initials-fallback background/text, mirroring `lr-chip`'s `tone` vocabulary; `neutral` (the
+  default) reads as a plain, unaccented circle.
+
+**Events:** none.
+
+**Slots:** default slot — icon/glyph content (e.g. an inline SVG), shown in place of the image and
+initials, e.g. to mark a chat avatar as "AI" vs. "user" with a role glyph. Takes priority over both
+`src` and `initials`. The glyph is treated as decorative (`aria-hidden`) — set `alt` alongside it
+for an accessible name.
+
+**CSS parts:** `base` (the outer circle/square container), `icon` (wrapper around the slotted
+icon/glyph, only shown while the slot has assigned content), `image` (the `<img>`, only rendered
+while `src` is set, hasn't failed to load, and no icon is slotted), `initials` (the fallback
+initials text, rendered whenever neither `icon` nor `image` is).
+
+**Themeable custom properties:** `--lr-avatar-size` (default `2rem`, swapped to `1.5rem`/`2.5rem`
+per `size="sm"`/`"lg"`), `--lr-avatar-bg` (default `var(--lr-color-surface-alt,
+var(--lr-color-border))`, swapped per `tone`), `--lr-avatar-color` (default
+`var(--lr-color-text)`, swapped per `tone`), `--lr-avatar-font-size` (default
+`var(--lr-font-size-sm)`) — the font size of the initials fallback, and of any `em`-sized slotted
+glyph. `size` swaps it per tier too (`var(--lr-font-size-xs)` at `sm`, `var(--lr-font-size-md)` at
+`lg`), so the initials track the circle instead of staying one fixed size across every tier;
+override it on the element for a size the built-in scale doesn't cover. Plus shared tokens
+`--lr-radius`/`-pill`, `--lr-font-size-sm`, `--lr-font-weight-semibold`.
+
+**Optional peer deps:** none.
+
+```html
+<lr-avatar initials="JS" tone="brand"></lr-avatar>
+<lr-avatar src="/users/42/photo.jpg" alt="Jane Smith" size="lg"></lr-avatar>
+<lr-avatar alt="Assistant"><svg viewBox="0 0 24 24"><!-- role glyph --></svg></lr-avatar>
+```
+
+**Known gotchas:**
+- an image load failure falls back to `initials` automatically. Changing `src` clears the failure
+  state so the replacement URL gets its own load attempt.
+- when `alt` or host `aria-label` supplies a name, the base preserves that name through the
+  initials fallback while hiding duplicate initials text from assistive technology.
+
+---

package/llms/components/lr-badge.md

@@ -0,0 +1,32 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/overlays.md — do not edit this file. -->
+
+# `lr-badge`
+
+- **Import** `import '@aceshooting/lyra-ui/components/overlays/badge/badge.js';` (registers the tag; side-effect import)
+- **Class** `LyraBadge`, also available unregistered from `@aceshooting/lyra-ui/components/overlays/badge/badge.class.js`
+- **Family** `components/overlays/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Documented with** `lr-tag` (same section below)
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-badge` and `lr-tag`
+
+Compact status labels. Both expose `variant: 'neutral' | 'brand' | 'success' | 'warning' | 'danger'`
+and `size: '2xs' | 'xs' | 's' | 'm' | 'l' | 'xl' = 'm'` (reflected) — the same visual-density scale
+`<lr-chip>` uses, for typography/padding/minimum block size; `m` preserves the original badge
+dimensions. `lr-tag` inherits `size` unchanged from `lr-badge` rather than redeclaring it.
+The two tags share the same visual contract; `lr-tag` is a semantic alias for migration-friendly
+markup.
+
+**Slots:** default content. **CSS parts:** `base`.
+
+**Themeable custom properties:** `--lr-badge-background`, `--lr-badge-color`, `--lr-badge-border`
+— the trio each `:host([variant])` rule rewrites (`neutral` defaults to
+`--lr-color-surface`/`-text`/`-border`; the other four to the matching `*-quiet` fill with the loud
+color for text and border). Set one directly on the element for a tint outside the five variants.
+`--lr-badge-font-size` (default `var(--lr-font-size-sm)`), `--lr-badge-padding-inline` (default
+`var(--lr-space-s)`), and `--lr-badge-min-height` (default `var(--lr-size-1-25rem)`) — the density
+trio each `:host([size])` rule rewrites to that step's font size, inline padding, and minimum block
+size; the `m` defaults above exactly reproduce the pre-`size` fixed badge treatment.