@aceshooting/lyra-ui 5.0.0 → 5.1.0

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

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

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

@@ -0,0 +1,70 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/charts.md — do not edit this file. -->
+
+# `lr-bar-chart`
+
+- **Import** `import '@aceshooting/lyra-ui/components/charts/chart/bar-chart.js';` (registers the tag; side-effect import)
+- **Class** `LyraBarChart`, also available unregistered from `@aceshooting/lyra-ui/components/charts/chart/bar-chart.class.js`
+- **Family** `components/charts/` — see `llms/index.md` for its siblings
+- **Optional peers** `chart.js`, `chartjs-plugin-zoom` — see `llms/peers.md`
+- **Documented with** `lr-line-chart`, `lr-pie-chart`, `lr-doughnut-chart`, `lr-radar-chart`, `lr-polar-area-chart`, `lr-bubble-chart`, `lr-scatter-chart` (same section below)
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## Typed subclasses: `lr-line-chart`, `lr-bar-chart`, `lr-pie-chart`, `lr-doughnut-chart`, `lr-radar-chart`, `lr-polar-area-chart`, `lr-bubble-chart`, `lr-scatter-chart`
+
+Each is `LyraChart` with `type` locked to a fixed value — respectively `line`, `bar`, `pie`,
+`doughnut`, `radar`, `polarArea`, `bubble`, `scatter` — via a real `get`/`set` accessor pair the
+shared `lockChartType()` helper installs on the subclass's own prototype (`declare type: '…'`
+narrows the TS type at compile time; the runtime lock is the `Object.defineProperty` pair alongside
+it — the same helper `lr-histogram` uses), not merely a class-field default a later assignment
+could still override.
+
+Everything else is inherited verbatim from `lr-chart`; each name below has the same type, default,
+and behavior there. **See `llms/components/lr-chart.md` for the details, code example, and gotchas
+of every entry in these lists.**
+
+**Properties:** `labels`, `datasets`, `legend`, `legendPosition` (attribute `legend-position`),
+`valueFormatter`, `area`, `zoom`, `height`, `xLabel` (`x-label`), `yLabel` (`y-label`), `y2Label`
+(`y2-label`), `beginAtZero` (`begin-at-zero`), `horizontal`, `stacked`, `config`, `accessibleLabel`
+(`accessible-label`), `accessibleDescription` (`accessible-description`), `showDataTable`
+(`show-data-table`), `chartArea` (readonly). `type` is the only member that differs: read-only,
+locked to this tag's value.
+
+**Methods:** `resetZoom()`, `refreshTheme()`.
+
+**Events:** `lr-zoom` (`detail: { zoomed: boolean }`), `lr-point-click` (`detail: { datasetIndex,
+index, label, value }`).
+
+**Slots:** `data-table`, `center`.
+
+**CSS parts:** `base`, `canvas`, `reset-zoom-button`, `description`, `data-table`, `center`.
+
+**Themeable custom properties:** `--lr-chart-height`, `--lr-chart-grid-color`,
+`--lr-chart-tick-color`, `--lr-chart-legend-color`, `--lr-chart-tooltip-bg`,
+`--lr-chart-tooltip-text`.
+
+**Optional peer deps:** same as `lr-chart` — `chart.js`, plus `chartjs-plugin-zoom` only once
+`zoom` is set.
+
+```html
+<lr-bar-chart legend></lr-bar-chart>
+<lr-pie-chart></lr-pie-chart>
+<script>
+  document.querySelector('lr-bar-chart').labels = ['A', 'B'];
+  document.querySelector('lr-bar-chart').datasets = [{ label: 'Count', data: [4, 9] }];
+
+  document.querySelector('lr-pie-chart').labels = ['A', 'B', 'C'];
+  document.querySelector('lr-pie-chart').datasets = [{ label: 'Share', data: [30, 45, 25], color: ['#2563eb', '#16a34a', '#dc2626'] }];
+</script>
+```
+
+**Known gotchas (in addition to the core `lr-chart` list in `llms/components/lr-chart.md`):**
+- `type` truly is locked per subclass: `<lr-pie-chart type="bar">` or `el.type = 'bar'` at runtime
+  is a genuine no-op (the accessor's setter silently ignores the write), not a footgun like a plain
+  overridden class-field default would be.
+- `lr-bubble-chart` needs `Series.points` entries with an `x`/`y`/`r` triple, but `Series.points`
+  is typed as `{x, y, label?}[]` with no `r` field — cast the array through `as unknown as
+  Series['points']` (or a local `BubblePoint` type) when constructing bubble data.
+
+---

package/llms/components/lr-box-plot.md

@@ -0,0 +1,67 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/charts.md — do not edit this file. -->
+
+# `lr-box-plot`
+
+- **Import** `import '@aceshooting/lyra-ui/components/charts/chart/box-plot.js';` (registers the tag; side-effect import)
+- **Class** `LyraBoxPlot`, also available unregistered from `@aceshooting/lyra-ui/components/charts/chart/box-plot.class.js`
+- **Family** `components/charts/` — see `llms/index.md` for its siblings
+- **Optional peers** `@sgratzl/chartjs-chart-boxplot`, `chart.js`, `chartjs-plugin-zoom` — see `llms/peers.md`
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-box-plot`
+
+Box-and-whisker chart from a precomputed five-number summary (no raw sample data sent to the
+browser). Does **not** extend `LyraChart` — a deliberately bespoke API.
+
+**Properties:**
+- `labels: string[] = []` (attribute: false)
+- `boxes: BoxPlotSeries[] = []` (attribute: false) — `BoxPlotSeries { label: string; data:
+  BoxPlotPoint[]; color?: string }`, `BoxPlotPoint { min, q1, median, q3, max }`
+- `legend: boolean = false`
+- `height: string = '280px'`
+- `yLabel: string = ''` (attribute `y-label`)
+- `beginAtZero: boolean = true` (attribute `begin-at-zero`)
+- `accessibleLabel: string = ''` (attribute `accessible-label`) — canvas name override; host
+  `aria-label` wins
+- `accessibleDescription: string = ''` (attribute `accessible-description`) — overrides the
+  localized five-number summary
+- `showDataTable: boolean = false` (attribute `show-data-table`) — reveals the accessible data table
+
+**Methods:** `refreshTheme()` re-reads canvas theme custom properties after an ancestor theme change.
+
+**Events:** none.
+
+**Slots:** `data-table` — an optional consumer-provided accessible table alternative.
+
+**CSS parts:** `base`, `canvas`, `description`, `data-table`
+
+**Themeable custom properties:** `--lr-chart-height`, `--lr-chart-grid-color`,
+`--lr-chart-tick-color`, `--lr-chart-legend-color`, `--lr-chart-tooltip-bg`,
+`--lr-chart-tooltip-text` — same host-level mechanism, token names, and defaults as `lr-chart`
+(also `getComputedStyle`-resolved on every draw), but declared in its own stylesheet, not a
+re-export: `lr-box-plot` has no `zoom`, so no `reset-zoom-button` chrome exists here.
+
+**Optional peer deps:** `@sgratzl/chartjs-chart-boxplot` (plus `chart.js` transitively, loaded
+independently of the base `chart-loader.ts`).
+
+```html
+<lr-box-plot y-label="Latency (ms)"></lr-box-plot>
+<script>
+  const bp = document.querySelector('lr-box-plot');
+  bp.labels = ['Run A', 'Run B'];
+  bp.boxes = [{ label: 'p50–p99', data: [{ min: 10, q1: 20, median: 30, q3: 45, max: 90 }, { min: 12, q1: 18, median: 25, q3: 35, max: 60 }] }];
+</script>
+```
+
+**Known gotchas:**
+- no raw `config` passthrough — limited to the properties above; can't reach the underlying
+  controller's own options (`itemRadius`, `outlierRadius`, `coef`).
+- Chart.js receives `effectiveLocale`; generated numeric summaries use it, the y axis moves to
+  logical start in RTL, canvas tooltip/axis colors are token-driven, and animation is disabled
+  under reduced motion.
+- If `@sgratzl/chartjs-chart-boxplot` fails to load, the component warns to the console and
+  resolves to no chart rather than throwing.
+
+---

package/llms/components/lr-branch-picker.md

@@ -0,0 +1,32 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/conversation.md — do not edit this file. -->
+
+# `lr-branch-picker`
+
+- **Import** `import '@aceshooting/lyra-ui/components/conversation/branch-picker/branch-picker.js';` (registers the tag; side-effect import)
+- **Class** `LyraBranchPicker`, also available unregistered from `@aceshooting/lyra-ui/components/conversation/branch-picker/branch-picker.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-branch-picker`
+
+The "‹ 2 / 5 ›" navigator across regenerated/edited variants of one message. Pure controlled: it
+never mutates its own `index` — the same contract `<lr-pagination>` already establishes for
+`page`. The host listens for `lr-branch-change`, swaps the displayed branch content, and applies
+the new `index` back. Renders nothing at all while `count < 2`, so a host can bind it unconditionally
+on every message regardless of whether that message actually has multiple branches yet.
+
+**Properties:** `index: number = 0` (reflected) and `count: number = 1` (reflected) — the current
+0-based branch and the total branch count. `label: string = ''`.
+
+**Methods:** `focus()` and `blur()` forward to the group wrapper.
+
+**Events:** `lr-branch-change` — a branch navigation was requested. `detail: { index }`, always a
+valid target (never past either bound); the consumer applies `index` after switching the displayed
+branch content.
+
+**CSS parts:** `base` (the group wrapper, `role="group"`), `previous-button`, `next-button`,
+`previous-glyph` and `next-glyph` (the chevron inside each button — target these to swap the
+arrow without restyling the button), and `position` (the visible "2 / 5" text).

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

@@ -0,0 +1,30 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/layout.md — do not edit this file. -->
+
+# `lr-breadcrumb-item`
+
+- **Import** `import '@aceshooting/lyra-ui/components/layout/breadcrumb/breadcrumb-item.js';` (registers the tag; side-effect import)
+- **Class** `LyraBreadcrumbItem`, also available unregistered from `@aceshooting/lyra-ui/components/layout/breadcrumb/breadcrumb-item.class.js`
+- **Family** `components/layout/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Documented with** `lr-breadcrumb` (same section below)
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-breadcrumb` and `lr-breadcrumb-item`
+
+Responsive navigation trail primitives.
+
+**`lr-breadcrumb` properties:** `accessibleLabel: string = ''` (attribute `aria-label`) — overrides
+the localized `"Breadcrumb"` name on the shadow-root `<nav>` landmark, which never inherits a host
+attribute on its own.
+
+**`lr-breadcrumb-item` properties:** `href: string = ''` (URL-sanitized; an unsafe scheme renders the
+non-link form) and `current: boolean = false` (reflected — renders a `<span aria-current="page">`
+instead of an `<a>`, even when `href` is set). Each item sets `role="listitem"` on itself.
+
+**Slots:** breadcrumb's default slot takes `lr-breadcrumb-item` children; an item's default slot is
+its label.
+
+**CSS parts:** breadcrumb `base` (the `<nav>`) and `list` (the `role="list"` flex row wrapping the
+slotted items); item `base` (the `<a>` or `<span>`).

package/llms/components/lr-breadcrumb.md

@@ -0,0 +1,30 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/layout.md — do not edit this file. -->
+
+# `lr-breadcrumb`
+
+- **Import** `import '@aceshooting/lyra-ui/components/layout/breadcrumb/breadcrumb.js';` (registers the tag; side-effect import)
+- **Class** `LyraBreadcrumb`, also available unregistered from `@aceshooting/lyra-ui/components/layout/breadcrumb/breadcrumb.class.js`
+- **Family** `components/layout/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Documented with** `lr-breadcrumb-item` (same section below)
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-breadcrumb` and `lr-breadcrumb-item`
+
+Responsive navigation trail primitives.
+
+**`lr-breadcrumb` properties:** `accessibleLabel: string = ''` (attribute `aria-label`) — overrides
+the localized `"Breadcrumb"` name on the shadow-root `<nav>` landmark, which never inherits a host
+attribute on its own.
+
+**`lr-breadcrumb-item` properties:** `href: string = ''` (URL-sanitized; an unsafe scheme renders the
+non-link form) and `current: boolean = false` (reflected — renders a `<span aria-current="page">`
+instead of an `<a>`, even when `href` is set). Each item sets `role="listitem"` on itself.
+
+**Slots:** breadcrumb's default slot takes `lr-breadcrumb-item` children; an item's default slot is
+its label.
+
+**CSS parts:** breadcrumb `base` (the `<nav>`) and `list` (the `role="list"` flex row wrapping the
+slotted items); item `base` (the `<a>` or `<span>`).

package/llms/components/lr-browser-frame.md

@@ -0,0 +1,51 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/agent-tools.md — do not edit this file. -->
+
+# `lr-browser-frame`
+
+- **Import** `import '@aceshooting/lyra-ui/components/agent-tools/browser-frame/browser-frame.js';` (registers the tag; side-effect import)
+- **Class** `LyraBrowserFrame`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/browser-frame/browser-frame.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-browser-frame`
+
+Presentational "agent computer" viewport: a screenshot/frame stream (or slotted live media), a
+read-only URL display, action-ping overlays, and take-over/stop affordances. No automation transport
+(no CDP/WebRTC/WebSocket) and no input relay — take-over is an event; the host swaps in its own
+interactive element (e.g. an iframe). No replay scrubber (compose `lr-playback` driving `frame-src`
+from a screenshot array); no console/network drawers (compose `lr-terminal`/`lr-json-viewer`); no
+pan/zoom of the frame content (slot the image/video inside a `lr-zoomable-frame` instead, though
+the pings overlay assumes the unzoomed content box in that composition).
+
+**Properties:** `frameSrc: string = ''` (attribute `frame-src`) — image/MJPEG stream URL rendered as
+an `<img>` (safe-URL-gated via `safeMediaSrc`); ignored once the default slot has content. `url:
+string = ''` — address shown read-only in the toolbar (`dir="ltr"`, truncating, full value in
+`title`). `status: 'idle' | 'connecting' | 'streaming' | 'stalled' = 'idle'` (reflected). `controller:
+'agent' | 'user' = 'agent'` (reflected) — who is driving; switches the take-over button's label.
+`pings: BrowserPing[] = []` (attribute: false, each `{ id, x, y, kind: 'click' | 'type' | 'scroll' |
+'move' }` — `x`/`y` are percent (0–100) of the frame's `object-fit: contain` content box,
+letterboxing-aware). `controls: boolean = true` — render the built-in take-over/stop buttons.
+
+**Slots:** default — host-owned live element (e.g. `<video>` or an interactive `<iframe>`), replacing
+the `frame-src` image. `actions` — extra toolbar controls.
+
+**Events:** `lr-take-over` — `detail: { controller }`, the *requested* controller (`'user'` when
+"Take over" is pressed, `'agent'` when "Hand back" is). `lr-stop` — stop the agent's browser
+session, no detail.
+
+**CSS parts:** `base` (`role="group"`), `toolbar`, `url`, `status` (`role="status"`),
+`controller-badge`, `actions`, `take-over-button`, `stop-button`, `viewport`, `frame` (the
+`frame-src` `<img>`, absent once the default slot is populated), `ping` (one action-ping marker,
+carries `data-kind`).
+
+**Themeable custom properties:** `--lr-browser-frame-aspect-ratio` (default `16 / 9`) — the
+viewport's aspect ratio.
+
+```html
+<lr-browser-frame status="streaming" url="https://example.com" .pings=${pings}
+  @lr-take-over=${(e) => setController(e.detail.controller)} @lr-stop=${() => stopSession()}
+></lr-browser-frame>
+```

package/llms/components/lr-bubble-chart.md

@@ -0,0 +1,70 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/charts.md — do not edit this file. -->
+
+# `lr-bubble-chart`
+
+- **Import** `import '@aceshooting/lyra-ui/components/charts/chart/bubble-chart.js';` (registers the tag; side-effect import)
+- **Class** `LyraBubbleChart`, also available unregistered from `@aceshooting/lyra-ui/components/charts/chart/bubble-chart.class.js`
+- **Family** `components/charts/` — see `llms/index.md` for its siblings
+- **Optional peers** `chart.js`, `chartjs-plugin-zoom` — see `llms/peers.md`
+- **Documented with** `lr-line-chart`, `lr-bar-chart`, `lr-pie-chart`, `lr-doughnut-chart`, `lr-radar-chart`, `lr-polar-area-chart`, `lr-scatter-chart` (same section below)
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## Typed subclasses: `lr-line-chart`, `lr-bar-chart`, `lr-pie-chart`, `lr-doughnut-chart`, `lr-radar-chart`, `lr-polar-area-chart`, `lr-bubble-chart`, `lr-scatter-chart`
+
+Each is `LyraChart` with `type` locked to a fixed value — respectively `line`, `bar`, `pie`,
+`doughnut`, `radar`, `polarArea`, `bubble`, `scatter` — via a real `get`/`set` accessor pair the
+shared `lockChartType()` helper installs on the subclass's own prototype (`declare type: '…'`
+narrows the TS type at compile time; the runtime lock is the `Object.defineProperty` pair alongside
+it — the same helper `lr-histogram` uses), not merely a class-field default a later assignment
+could still override.
+
+Everything else is inherited verbatim from `lr-chart`; each name below has the same type, default,
+and behavior there. **See `llms/components/lr-chart.md` for the details, code example, and gotchas
+of every entry in these lists.**
+
+**Properties:** `labels`, `datasets`, `legend`, `legendPosition` (attribute `legend-position`),
+`valueFormatter`, `area`, `zoom`, `height`, `xLabel` (`x-label`), `yLabel` (`y-label`), `y2Label`
+(`y2-label`), `beginAtZero` (`begin-at-zero`), `horizontal`, `stacked`, `config`, `accessibleLabel`
+(`accessible-label`), `accessibleDescription` (`accessible-description`), `showDataTable`
+(`show-data-table`), `chartArea` (readonly). `type` is the only member that differs: read-only,
+locked to this tag's value.
+
+**Methods:** `resetZoom()`, `refreshTheme()`.
+
+**Events:** `lr-zoom` (`detail: { zoomed: boolean }`), `lr-point-click` (`detail: { datasetIndex,
+index, label, value }`).
+
+**Slots:** `data-table`, `center`.
+
+**CSS parts:** `base`, `canvas`, `reset-zoom-button`, `description`, `data-table`, `center`.
+
+**Themeable custom properties:** `--lr-chart-height`, `--lr-chart-grid-color`,
+`--lr-chart-tick-color`, `--lr-chart-legend-color`, `--lr-chart-tooltip-bg`,
+`--lr-chart-tooltip-text`.
+
+**Optional peer deps:** same as `lr-chart` — `chart.js`, plus `chartjs-plugin-zoom` only once
+`zoom` is set.
+
+```html
+<lr-bar-chart legend></lr-bar-chart>
+<lr-pie-chart></lr-pie-chart>
+<script>
+  document.querySelector('lr-bar-chart').labels = ['A', 'B'];
+  document.querySelector('lr-bar-chart').datasets = [{ label: 'Count', data: [4, 9] }];
+
+  document.querySelector('lr-pie-chart').labels = ['A', 'B', 'C'];
+  document.querySelector('lr-pie-chart').datasets = [{ label: 'Share', data: [30, 45, 25], color: ['#2563eb', '#16a34a', '#dc2626'] }];
+</script>
+```
+
+**Known gotchas (in addition to the core `lr-chart` list in `llms/components/lr-chart.md`):**
+- `type` truly is locked per subclass: `<lr-pie-chart type="bar">` or `el.type = 'bar'` at runtime
+  is a genuine no-op (the accessor's setter silently ignores the write), not a footgun like a plain
+  overridden class-field default would be.
+- `lr-bubble-chart` needs `Series.points` entries with an `x`/`y`/`r` triple, but `Series.points`
+  is typed as `{x, y, label?}[]` with no `r` field — cast the array through `as unknown as
+  Series['points']` (or a local `BubblePoint` type) when constructing bubble data.
+
+---

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

@@ -0,0 +1,30 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/layout.md — do not edit this file. -->
+
+# `lr-button-group`
+
+- **Import** `import '@aceshooting/lyra-ui/components/layout/button-group/button-group.js';` (registers the tag; side-effect import)
+- **Class** `LyraButtonGroup`, also available unregistered from `@aceshooting/lyra-ui/components/layout/button-group/button-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-button-group`
+
+Responsive semantic grouping primitive for related action controls. It preserves the slotted
+controls and exposes `role="group"` on its internal wrapper.
+
+**Properties:**
+- `orientation: 'horizontal' | 'vertical' = 'horizontal'` (reflected)
+- `label: string = ''` — accessible group name; a host `aria-label` is used when `label` is empty
+
+**Slots:** default action controls.
+
+**CSS parts:** `base` (the `role="group"` flex wrapper; wraps, and goes full-width below a 20rem
+container inline-size).
+
+**Themeable custom properties:** `--lr-button-group-gap` (default `var(--lr-space-2xs)`) — gap
+between slotted controls on both axes.
+
+---

package/llms/components/lr-button.md

@@ -0,0 +1,89 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/forms.md — do not edit this file. -->
+
+# `lr-button`
+
+- **Import** `import '@aceshooting/lyra-ui/components/forms/button/button.js';` (registers the tag; side-effect import)
+- **Class** `LyraButton`, also available unregistered from `@aceshooting/lyra-ui/components/forms/button/button.class.js`
+- **Family** `components/forms/` — 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-button`
+
+A generic action-button primitive. Renders an internal native `<button>`; `type="submit"`/
+`type="reset"` are handled by the component itself via the host's own `closest('form')`, since a
+shadow-internal native button doesn't participate in an ancestor form's submission on its own.
+
+**Properties:**
+- `variant: 'neutral' | 'brand' | 'success' | 'warning' | 'danger' = 'neutral'` (reflected)
+- `appearance: 'accent' | 'filled' | 'outlined' | 'plain' | 'quiet' | 'link' = 'filled'` (reflected)
+  — `'accent'` is a
+  loud, high-contrast filled tier,
+  distinct from `'filled'` for `variant="neutral"` specifically (`'filled'` reads the ambient
+  surface color there; `'accent'` reads a solid neutral fill). `'quiet'` is a de-emphasized tier:
+  transparent background with a bordered, muted-text chrome that fills to `--lr-color-surface` on
+  hover; its text/border tokens are **not** variant-swapped, so `variant` has no effect on it.
+  `'link'` is a true inline-link tier:
+  zero chrome (no padding, border, border-radius, or `min-block-size` floor), underlined
+  (`text-underline-offset: var(--lr-size-0-15rem)`), colored from `--lr-button-accent` (the same token `'plain'`
+  uses, so `variant` still selects the link color) and inheriting the surrounding font-size/weight
+  — for a text link that flows within a sentence rather than a button-shaped control. Declared
+  after the per-`size` rules, so it overrides them whatever `size` is set
+- `size: '2xs' | 'xs' | 's' | 'm' | 'l' | 'xl' = 'm'` (reflected) — `'2xs'` is the tightest tier,
+  below `'xs'`, for dense chrome; `'m'` is the standard one
+- `type: 'button' | 'submit' | 'reset' = 'button'`
+- `loading: boolean = false` (reflected) — shows an internal spinner and disables the button without
+  clearing `disabled`
+- `disabled: boolean = false` (reflected)
+
+The shared `m` size uses `--lr-font-size-m`. The internal button follows the host's inline size through `--lr-button-width` (default
+`100%`), and each size tier's `min-block-size` floor is exposed as its own token (see below).
+
+**Getters/methods:** `click()`, `focus(options?)`, and `blur()` — forwarded to the internal native
+`<button>`; `click()` also runs the component's submit/reset behavior.
+
+**Events:** none (a plain native `click` bubbles and composes through the shadow boundary
+unmodified; disabled while `disabled` or `loading`).
+
+**Slots:** default (label content), `start` (leading icon/content), `end` (trailing icon/content).
+
+**CSS parts:** `base`, `label`, `start`, `end`, `spinner` (present only while `loading`).
+
+**Themeable custom properties:** `--lr-button-width`, `--lr-button-accent`, `--lr-button-fill`,
+`--lr-button-on-fill`, `--lr-button-border` (each swapped by the active `variant`, default
+`neutral` falls back to plain text/surface/border tokens), `--lr-button-accent-fill`,
+`--lr-button-accent-on-fill` (the `appearance="accent"` fill/foreground pair; `neutral` falls
+back to `--lr-color-neutral`/`--lr-color-on-neutral`, every other variant reuses that variant's own
+loud fill token), `--lr-button-outlined-border` (default `--lr-color-border-strong`, the
+`appearance="outlined"` border color — variant-independent, unlike `--lr-button-border`),
+`--lr-button-quiet-text` (default `--lr-color-text-quiet`) and `--lr-button-quiet-border` (default
+`--lr-color-border`) — the `appearance="quiet"` foreground/border pair, also variant-independent,
+`--lr-button-hover-brightness` (default `1.08`, the `:hover` filter intensity),
+`--lr-button-active-scale` (default `0.9875`, the `:active` press-scale, disabled under
+`prefers-reduced-motion`), `--lr-button-spinner-duration` (default `1s`, the `loading` spinner's
+rotation period; forced to `0.001ms` under `prefers-reduced-motion`), and the per-`size`
+`min-block-size` floors `--lr-button-size-2xs` (`1.25rem`), `--lr-button-size-xs` (`1.5rem`),
+`--lr-button-size-s` (`1.75rem`), `--lr-button-size-m` (`2rem`), `--lr-button-size-l` (`2.5rem`),
+`--lr-button-size-xl` (`3rem`) — each read only by its own `size` tier, and all ignored by
+`appearance="link"`.
+
+**Optional peer deps:** none.
+
+```html
+<lr-button variant="brand" appearance="filled">Save</lr-button>
+<lr-button variant="neutral" appearance="accent">Save</lr-button>
+<lr-button appearance="plain" aria-label="Close dialog"><svg slot="start">...</svg></lr-button>
+<p>The message failed. <lr-button appearance="link" variant="brand">Retry</lr-button></p>
+```
+
+**Known gotchas:**
+- A host `aria-label` is forwarded to the internal button as a literal string (for an icon-only
+  button); an external `aria-labelledby`/`aria-describedby` idref is not copied across the shadow
+  boundary.
+- Is form-associated (`static formAssociated = true` + `attachInternals()`), so it participates in
+  an ancestor `<form>.elements` the same way `wa-button` does — a sibling text field's own
+  Enter-to-submit lookup (which scans `form.elements` for a `type === 'submit'` control) finds it.
+
+---