@aceshooting/lyra-ui 5.0.0 → 5.1.0

package/llms/components/lr-app-rail.md

@@ -0,0 +1,218 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/layout.md — do not edit this file. -->
+
+# `lr-app-rail`
+
+- **Import** `import '@aceshooting/lyra-ui/components/layout/app-rail/app-rail.js';` (registers the tag; side-effect import)
+- **Class** `LyraAppRail`, also available unregistered from `@aceshooting/lyra-ui/components/layout/app-rail/app-rail.class.js`
+- **Family** `components/layout/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Documented with** `lr-app-rail-item` (same section below)
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-app-rail`
+
+A responsive navigation rail that adapts across three presentations as the *viewport* narrows (not
+this element's own inline size): `'full'` (nav items show icon + label, inline), `'icon-only'` (a
+narrower inline rail, icons only), and `'mobile'` (hidden behind a toggle button; opening it shows a
+focus-trapped floating overlay over the page). First-party invention (no Web Awesome equivalent).
+Breakpoints are viewport-width `matchMedia()` queries against `icon-only-breakpoint`/
+`mobile-breakpoint`, not a `ResizeObserver` on this element — presentation tracks the actual device/
+window width the way a native OS shell's navigation does, not however much horizontal space a
+particular layout happens to give it. `[part="base"]` (the inline `'full'`/`'icon-only'`
+presentation) and `[part="panel"]` (the mobile overlay) are the *same* element promoted in place
+across modes (mirrors `<lr-widget>`'s fullscreen mode) — never both at once, and slotted nav
+content is never duplicated.
+
+Opting in to `resizable` adds a continuously draggable width for the `'full'` state: a
+`[part="resizer"]` handle (pointer-drag and Left/Right-arrow keyboard stepping, RTL-aware) clamped to
+`[minRailWidthPx, maxRailWidthPx]`, with no built-in persistence — a consumer that wants the chosen
+width to survive a reload listens for `lr-rail-resize` and persists `railWidthPx` itself.
+`preferredMode` separately lets a host manually prefer `'full'`/`'icon-only'` for the non-mobile
+breakpoint axis (e.g. a user's own collapse toggle) while `mobile-breakpoint` continues to be tracked
+automatically regardless — it's only consulted while `mode` isn't force-pinned via the `mode`
+accessor itself, which still takes full priority.
+
+**Properties:**
+- `mode: AppRailMode` (custom accessor, reflected) — the getter always returns one of the three real
+  modes (`'full'|'icon-only'|'mobile'`), never `'auto'`. The setter accepts
+  `AppRailModeInput` (`AppRailMode | 'auto'`): assigning `'full'`/`'icon-only'`/`'mobile'` forces
+  that mode and stops the element responding to breakpoint changes; assigning the write-only
+  sentinel `'auto'` releases the force and immediately re-syncs to the current viewport width,
+  resuming automatic tracking. Settable via the `mode` attribute too (`mode="icon-only"`,
+  `mode="auto"`).
+- `iconOnlyBreakpoint: string = '960px'` (attribute `icon-only-breakpoint`) — any valid CSS length,
+  used directly in a `(max-width: ...)` media query; below it the rail switches from `'full'` to
+  `'icon-only'`.
+- `mobileBreakpoint: string = '600px'` (attribute `mobile-breakpoint`) — same mechanism; below it the
+  rail switches from `'icon-only'` to `'mobile'`. Should be smaller than `iconOnlyBreakpoint` to
+  produce all three states as the viewport narrows.
+- `open: boolean = false` (reflected) — whether the mobile floating overlay is shown. Only meaningful
+  while `mode` is `'mobile'` — the value is preserved (not reset) while another mode is active, but
+  no overlay chrome renders until `mode` is `'mobile'` again. Set this directly, or use the built-in
+  toggle button — there is no separate `show()`/`hide()` pair.
+- `label: string = 'Navigation'` — accessible name for the rail's navigation landmark, and for its
+  dialog role while the mobile overlay is open. A host-level `aria-label` attribute (see below)
+  takes precedence over this when both are set.
+- `preferredMode?: 'full' | 'icon-only' | null` (attribute `preferred-mode`) — manually prefers
+  `'full'` or `'icon-only'` for the non-mobile breakpoint axis, while `mobile-breakpoint` continues to
+  be tracked automatically regardless — e.g. a user's manual collapse toggle that should still yield
+  to a genuinely too-narrow-for-any-inline-rail viewport. Only consulted while `mode` isn't
+  force-pinned via its own accessor (see above) — that continues to take full priority, unchanged.
+  Unset (the default, `null`) reproduces the original breakpoint-only behavior exactly.
+- `hideToggle: boolean = false` (reflected, attribute `hide-toggle`) — suppresses the built-in mobile
+  `[part='toggle']` hamburger/close button entirely, for a consumer that already owns an external
+  mobile-menu toggle wired to this rail's own `open` property. `false` (the default) reproduces the
+  exact existing output; note `open` still has no built-in external trigger of its own once this is
+  set, since `lr-toggle` only fires from the toggle button being activated.
+- `resizable: boolean = false` (reflected) — opts a continuously draggable width in for the `'full'`
+  state, exposing a `[part='resizer']` handle clamped to `[minRailWidthPx, maxRailWidthPx]`. `false`
+  (the default) renders no resizer and leaves the fixed-width `--lr-app-rail-width` CSS token
+  exactly as before this property existed.
+- `railWidthPx?: number` (attribute `rail-width-px`) — the rail's current width in px while
+  `resizable`; settable/gettable directly. Unset defers to `--lr-app-rail-width`'s own resolved
+  width.
+- `minRailWidthPx: number = 190` (attribute `min-rail-width-px`) — minimum `railWidthPx` a
+  drag/keyboard resize can reach.
+- `maxRailWidthPx: number = 440` (attribute `max-rail-width-px`) — maximum `railWidthPx` a
+  drag/keyboard resize can reach.
+- `dragging: boolean = false` (reflected) — `true` for the duration of an active pointer-driven
+  resize drag (not a keyboard step); reflected so a consumer (or this component's own styles) can
+  suppress `[part='base']`'s `transition: inline-size` during the drag, which otherwise visibly
+  "chases" the pointer instead of tracking it 1:1. Effectively read-only (this component owns the
+  transitions), but a plain reflected property like every other boolean here.
+
+Also settable as a plain `aria-label` attribute (not a reactive property): overrides the computed
+`label`/localized-default accessible name on both the navigation landmark and the mobile dialog
+role, matching `<lr-date-input>`'s `accessibleLabel`.
+
+**Events:** `lr-mode-change` (`detail: AppRailModeChangeDetail` = `{ mode: AppRailMode }`; the
+effective mode changed, whether from a breakpoint crossing or an explicit `mode` assignment — not
+fired for a redundant reassignment to the mode already in effect), `lr-toggle`
+(`detail: AppRailToggleDetail` = `{ open: boolean }`; the mobile overlay opened or closed — via the
+built-in toggle button, Escape, a backdrop click, a nav-item click while open, or a breakpoint/forced
+mode change leaving `'mobile'` while open — not fired when a consumer sets `open` directly),
+`lr-rail-resize` (`detail: AppRailResizeDetail` = `{ widthPx: number }`; the `resizable` rail's
+width changed via drag or keyboard stepping — not fired when a consumer sets `railWidthPx` directly).
+
+**Slots:** default (nav items — generic slotted content, e.g. `<a>`/`<button>` elements the consumer
+builds with its own icon+label structure; clicking anywhere in this slot closes the mobile overlay if
+open), `header` (logo/brand content, shown above the nav items in every mode), `footer` (a trailing
+user/settings trigger, shown below the nav items).
+
+**CSS parts:** `base`, `header`, `nav`, `footer`, `toggle` (hidden via CSS outside `'mobile'` mode, or
+entirely via `hideToggle`), `backdrop`, `panel` (`base`/`panel` are mutually exclusive on the same
+underlying element — see above), `resizer` (the `resizable` opt-in's drag handle, only rendered while
+`resizable` and `mode` is `'full'`; its hit target is `--lr-icon-button-size`-wide), `resizer-track`
+(the slim 3px visible drag line centered inside that hit target, tinted `--lr-color-brand` on hover).
+
+**Themeable custom properties:** `--lr-app-rail-width` (default `15rem` — the inline rail width in
+`'full'` mode), `--lr-app-rail-icon-width` (default `4rem` — the inline rail width in `'icon-only'`
+mode), `--lr-app-rail-mobile-width` (default `18rem`, capped at `85vw` — the mobile overlay panel
+width), `--lr-app-rail-overlay-color` (default `var(--lr-color-overlay)` — the mobile backdrop scrim
+color; component-specific since no shared token exists), plus shared tokens (`--lr-color-border`,
+`--lr-color-surface`, `--lr-color-text`, `--lr-color-brand`, `--lr-color-brand-quiet`,
+`--lr-space-*`, `--lr-radius`, `--lr-shadow`, `--lr-icon-button-size`,
+`--lr-focus-ring-*`, `--lr-transition-base`). `resizable`'s width is driven entirely by
+`railWidthPx`'s inline `inline-size` style rather than a new custom property.
+
+**Optional peer deps:** none.
+
+```html
+<lr-app-rail label="Main navigation" icon-only-breakpoint="960px" mobile-breakpoint="600px" resizable>
+  <span slot="header"><img src="/logo.svg" alt="Acme" /></span>
+  <a href="/inbox" aria-label="Inbox"><svg aria-hidden="true">...</svg><span>Inbox</span></a>
+  <a href="/settings" aria-label="Settings"><svg aria-hidden="true">...</svg><span>Settings</span></a>
+  <span slot="footer"><button>Profile</button></span>
+</lr-app-rail>
+<script type="module">
+  const rail = document.querySelector('lr-app-rail');
+  rail.addEventListener('lr-rail-resize', (e) => localStorage.setItem('railWidthPx', String(e.detail.widthPx)));
+</script>
+```
+```ts
+rail.mode = 'icon-only'; // force a presentation regardless of viewport width
+rail.mode = 'auto';      // release the force, resume live breakpoint tracking
+```
+
+The package root also exports a pure `computeAppRailMode(iconOnlyMatches: boolean, mobileMatches:
+boolean, preferredMode?: 'full' | 'icon-only' | null): AppRailMode` resolver (plus the
+`AppRailMode`/`AppRailModeInput`/`AppRailModeChangeDetail`/`AppRailToggleDetail`/`AppRailResizeDetail`
+types) — the same logic the element's internal `matchMedia` listeners call, exposed standalone so a
+consumer can compute or unit-test the same resolution without a real browser window. `mobileMatches`
+wins over everything else when true (the viewport is narrower than both breakpoints at once);
+otherwise `preferredMode` (when set) wins over `iconOnlyMatches`.
+
+The mobile state keeps its own panel template rather than nesting `<lr-dialog>`, while its modal
+behavior participates in the shared overlay stack. It is a plain `<div>` with an explicit
+`role="navigation"` (swapping to `role="dialog"` while the overlay is open) rather than a literal
+`<nav>` tag, since a
+`<nav>`'s implicit role can't be overridden to `role="dialog"` without an `aria-allowed-role`
+violation. In `'icon-only'` mode, slotted nav items lose their visible text label — give each one a
+real accessible name (`aria-label`, visually hidden text, or `title`) regardless, since this
+component only lays out whatever is slotted and can't inspect or fix up a consumer's own markup.
+
+**Known gotchas:**
+- `mode`'s setter accepts the wider `AppRailModeInput` (including the `'auto'` sentinel) but the
+  getter's return type is the narrower `AppRailMode` — assigning `'auto'` is a one-way instruction,
+  not a value read back later; there is no `isForced`-style property to check whether the rail is
+  currently locked to a mode or tracking the viewport.
+- reassigning `icon-only-breakpoint`/`mobile-breakpoint` after first render tears down and rebuilds
+  the `matchMedia` listeners, but does not itself un-force a previously-forced `mode` — if a consumer
+  set `mode = 'icon-only'`, changing the breakpoints won't resume auto-tracking until `mode = 'auto'`
+  is set explicitly.
+- leaving `'mobile'` mode while `open` (via a breakpoint crossing or a forced `mode` reassignment)
+  auto-closes the overlay through the same path as the toggle button, so `lr-toggle` still fires
+  and the scroll lock/focus trap still release normally — a consumer listening only for explicit
+  toggle-button clicks would miss this closure.
+- the mobile panel is also given `inert` whenever `mode === 'mobile'` and `open` is `false` — it's
+  removed from the accessibility tree and tab order via `inert` at the same time it's hidden visually
+  via `transform: translateX(-100%)`, both applied simultaneously rather than one implying the other.
+- the offscreen slide direction for the mobile panel is flipped for RTL via a `:dir(rtl)` CSS
+  selector (`translateX(100%)`), not through the shared `internal/rtl.ts` JS helper used for pointer/
+  keyboard math elsewhere in this library — a physical `transform` isn't expressible with logical
+  properties, so this one case is handled purely in CSS.
+- a reconnect that preserves the same element instance (e.g. a drag-and-drop reparent) resumes its
+  shared overlay registration and re-acquires the scroll lock if the overlay was still active
+  across the move — `disconnectedCallback`/`connectedCallback` fire back-to-back with no update in
+  between, so `willUpdate()` alone wouldn't otherwise notice.
+- `resizable`'s drag handle is pointer-only (`pointerdown`/`pointermove`/`pointerup`/
+  `pointercancel`/`lostpointercapture`) plus discrete Left/Right-arrow keyboard stepping (8px per
+  press, RTL-aware) — there's no dedicated touch gesture beyond what Pointer Events already unify.
+- reassigning `railWidthPx` while `resizable` is unset has no visible effect on the rendered width —
+  the fixed-width `--lr-app-rail-width` token still governs `'full'`-mode width until `resizable`
+  is also set.
+- reassigning `icon-only-breakpoint`/`mobile-breakpoint`/`preferredMode` does not itself un-force a
+  previously-forced `mode` — same caveat as above, `preferredMode` is only consulted while `mode`
+  isn't force-pinned.
+
+### `lr-app-rail-item`
+
+An explicit navigation item for `<lr-app-rail>`. It renders an accessible link when `href` is
+set and enabled, otherwise a button; the rail can add its `icon-only` presentation state without
+removing the label from the accessibility tree.
+
+**Properties:**
+- `href: string = ''` — optional destination. Without it, the item renders as a button.
+- `target: string = ''` — optional link target.
+- `disabled: boolean = false` (reflected) — prevents activation while retaining the item in the rail.
+- `active: boolean = false` (reflected) — marks this as the destination for the current page/view;
+  reflects `aria-current="page"` on `[part='base']` and drives the active visual treatment. The rail
+  has no built-in routing, so the consumer sets this per item (e.g. by comparing `href` against the
+  current location).
+- `tooltip: boolean = false` (reflected) — opt-in hover/focus flyout (`[part='tooltip']`) showing
+  this item's label text while the rail's `icon-only` mode (set externally by the parent
+  `<lr-app-rail>` as the viewport narrows) hides it from view. No effect outside icon-only mode,
+  since the label is already visible there. `false` (the default) reproduces the exact existing
+  output.
+
+**Slots:** default (the visible label), `icon` (the leading icon, hidden from assistive technology
+when the item has an explicit `aria-label`).
+
+**CSS parts:** `base`, `icon`, `label`, `tooltip` (the hover/focus label flyout, only rendered while
+`tooltip` is set, the item is `icon-only`, and it is hovered or focused).
+
+**Optional peer deps:** none.
+
+---

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

@@ -0,0 +1,36 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/viewers.md — do not edit this file. -->
+
+# `lr-archive-viewer`
+
+- **Import** `import '@aceshooting/lyra-ui/components/viewers/archive-viewer/archive-viewer.js';` (registers the tag; side-effect import)
+- **Class** `LyraArchiveViewer`, also available unregistered from `@aceshooting/lyra-ui/components/viewers/archive-viewer/archive-viewer.class.js`
+- **Family** `components/viewers/` — see `llms/index.md` for its siblings
+- **Optional peers** `jszip` — see `llms/peers.md`
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-archive-viewer`
+
+Lists entry names and human-readable uncompressed sizes inside a `.zip` archive using the optional
+`jszip` peer. It is listing-only: entry content is never rendered or previewed. Each entry's size is
+read straight from JSZip's local file header (`uncompressedSize`) when available, falling back to
+fully decompressing only the rare entry missing that header field. The list composes
+`<lr-virtual-list>` for large archives.
+
+**Properties:** `src` and `name` are strings — `name` (or a host-level `aria-label`) names the
+listing region as `role="region"`; with neither set, the region is unnamed.
+
+**Events:** `lr-render-error` with `detail.error` when fetching or parsing fails.
+
+**CSS parts:** `base`, `entry`, `entry-icon`, `entry-name`, `entry-size`, `spinner`, and `error`.
+
+**Exports:** `ArchiveEntry` — `{ name: string; dir: boolean; size: number }`.
+
+**Optional peer dependency:** install `jszip` with `pnpm add jszip`. The lazy registry registers
+`application/zip` and `application/x-zip-compressed`, with a `.zip` filename fallback, and imports
+the viewer only when a matching archive is opened. `.tar`, `.rar`, and other archive formats fall
+through to `<lr-document-preview>`'s generic download fallback.
+
+Remote resources are capped at 25 MB; exceeding it surfaces the localized
+`documentPreviewResourceTooLarge` message instead of the entry listing.

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

@@ -0,0 +1,60 @@
+<!-- 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-next`, `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`).
+
+```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,50 @@
+<!-- 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-time`, `cue-speaker`, `cue-text`, and `error`.
+
+**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`).