@aceshooting/lyra-ui 5.0.0 → 5.1.0

package/llms/components/lr-pagination.md

@@ -0,0 +1,88 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/data.md — do not edit this file. -->
+
+# `lr-pagination`
+
+- **Import** `import '@aceshooting/lyra-ui/components/data/pagination/pagination.js';` (registers the tag; side-effect import)
+- **Class** `LyraPagination`, also available unregistered from `@aceshooting/lyra-ui/components/data/pagination/pagination.class.js`
+- **Family** `components/data/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-pagination`
+
+Controlled page navigation for server-side or client-side data sets: previous/next buttons, a
+validated numeric page jump, a localized item-range summary, and a polite announcement after the
+host applies a requested page. The component owns no data fetching and never mutates `page`.
+
+**Properties and getters:**
+- `page: number = 1` (reflected) — the currently applied page. Runtime values are presented within
+  the valid `1..pageCount` range, but the public property itself remains controlled and is not
+  rewritten by the component
+- `pageSize: number = 20` (attribute `page-size`) — items per page; finite values are truncated to
+  a non-negative integer for the derived calculations, and zero produces no pages
+- `totalItems: number = 0` (attribute `total-items`) — total item count; finite values are truncated
+  to a non-negative integer for display and page-count calculations
+- `pageCount: number` (readonly getter) — `ceil(totalItems / pageSize)` after the normalization
+  above, or `0` when either normalized input is zero
+- `disabled: boolean = false` (reflected)
+- `loading: boolean = false` (reflected) — disables all controls and sets `aria-busy="true"` on the
+  internal navigation landmark
+- `hideSummary: boolean = false` (attribute `hide-summary`, reflected) — omits the built-in range
+  summary while retaining the controls
+- `size: 'xs'|'s'|'m'|'l'|'xl' = 'm'` (reflected) — changes control height and type size
+- `itemLabel: string = ''` (attribute `item-label`) — custom item noun used in the summary; empty
+  selects the localized singular `item` or plural `items` key
+- `accessibleLabel: string | null = null` (attribute `aria-label`) — host accessible-name override
+  forwarded to the internal `<nav>` landmark; takes precedence over `label`
+- `label: string = 'Pagination'` — fallback accessible name for the internal `<nav>` landmark
+- `pageLabel: string = 'Page'` (attribute `page-label`) — accessible name for the page-jump input
+- `previousLabel: string = 'Previous'` (attribute `previous-label`), `nextLabel: string = 'Next'`
+  (attribute `next-label`) — accessible names for the icon-only directional buttons
+
+Built-in property defaults resolve through the locale registry. A property value customized away
+from its built-in default is treated as an explicit per-instance wording override.
+
+**Events:** `lr-page-change` (`detail: { page: number }`, bubbles and composes, non-cancelable) —
+emitted for a valid, different requested page. The host applies `event.detail.page` back to `page`
+after routing, fetching, or any other policy decision.
+The internal page input's `focus` and `blur` are also bridged as bubbling, composed host events.
+
+**Methods:** `focus(options?)` and `blur()` forward to the numeric page input.
+
+**Slots:** none.
+
+**CSS parts:** `base`, `summary`, `controls`, `previous-button`, `previous-icon`, `page-field`,
+`page-input`, `page-count`, `next-button`, `next-icon`, `live-region`.
+
+**Themeable custom properties:** `--lr-pagination-control-size` and
+`--lr-pagination-font-size` (both default from `size`), plus shared color, spacing, border, radius,
+disabled-opacity, and focus-ring tokens.
+
+**Optional peer deps:** none.
+
+```html
+<lr-pagination total-items="237" page-size="20"></lr-pagination>
+<script>
+  const pagination = document.querySelector('lr-pagination');
+  pagination.addEventListener('lr-page-change', async (event) => {
+    await loadPage(event.detail.page);
+    pagination.page = event.detail.page;
+  });
+</script>
+```
+
+**Known gotchas:**
+- user activation only emits an intent. Until the host applies a new `page`, the numeric input
+  returns to the currently controlled value; assigning the page triggers the localized
+  `role="status"` announcement
+- the jump input accepts only whole pages in `1..pageCount`; empty, fractional, and out-of-range
+  drafts expose `aria-invalid="true"` and emit nothing
+- zero items, zero page size, `disabled`, and `loading` all disable the navigation controls. The
+  empty summary is still rendered via the localized `paginationEmptySummary` message
+  (`'{total} {itemLabel}'`, producing `0 items` in the default locale) unless `hide-summary` is set
+- below a 20rem container allocation the summary and controls stack; the breakpoint responds to
+  the component's own inline size, not the viewport. Previous/next icons also mirror under RTL
+
+---

package/llms/components/lr-path-strip.md

@@ -0,0 +1,55 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/retrieval.md — do not edit this file. -->
+
+# `lr-path-strip`
+
+- **Import** `import '@aceshooting/lyra-ui/components/retrieval/path-strip/path-strip.js';` (registers the tag; side-effect import)
+- **Class** `LyraPathStrip`, also available unregistered from `@aceshooting/lyra-ui/components/retrieval/path-strip/path-strip.class.js`
+- **Family** `components/retrieval/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-path-strip`
+
+A linear node → relation → node chain rendering "why A connects to B" (GraphRAG local-search
+reasoning paths) as a compact, horizontally scrollable strip. One-dimensional and presentational: no
+path finding, no branching, no per-element popovers.
+
+**Properties:**
+- `path: LyraPathElement[] = []` (attribute: false) — a flat alternating sequence:
+  `{ kind: 'node'; node: LyraEntity } | { kind: 'edge'; relation: string; directed?: boolean;
+  reverse?: boolean }`
+- `label: string = ''`
+
+**Events:** `lr-entity-activate` (`detail: { id }`, a node element activated),
+`lr-relation-activate` (`detail: { relation, sourceId?, targetId? }`, an edge element activated —
+source/target resolved from the adjacent node elements, `undefined` when the path is malformed at
+that position).
+
+**Slots:** none.
+
+**CSS parts:** `base` (hosts the delegated roving-tabindex keydown handler), `node` (a `<button>`),
+`relation` (a `<button>`), `arrow` (`aria-hidden`, logical — mirrors under RTL), `empty` (shown when
+`path` is empty).
+
+**Themeable custom properties:** shared tokens only.
+
+**Optional peer deps:** none.
+
+```html
+<lr-path-strip></lr-path-strip>
+<script>
+  document.querySelector('lr-path-strip').path = [
+    { kind: 'node', node: { id: 'a', label: 'Ada Lovelace' } },
+    { kind: 'edge', relation: 'wrote', directed: true },
+    { kind: 'node', node: { id: 'b', label: 'Notes on the Analytical Engine' } },
+  ];
+</script>
+```
+
+**Known gotchas:**
+- Purely presentational rendering of a caller-supplied path — it never computes shortest paths or
+  fetches relationship data itself, and never branches (one linear chain per instance).
+
+---

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

@@ -0,0 +1,78 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/viewers.md — do not edit this file. -->
+
+# `lr-pdf-viewer`
+
+- **Import** `import '@aceshooting/lyra-ui/components/viewers/pdf-viewer/pdf-viewer.js';` (registers the tag; side-effect import)
+- **Class** `LyraPdfViewer`, also available unregistered from `@aceshooting/lyra-ui/components/viewers/pdf-viewer/pdf-viewer.class.js`
+- **Family** `components/viewers/` — see `llms/index.md` for its siblings
+- **Optional peers** `pdfjs-dist` — see `llms/peers.md`
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-pdf-viewer`
+
+Fetches a PDF and renders its pages with the optional `pdfjs-dist` peer. Pages are virtualized through
+`lr-virtual-list`, and PDF.js's selectable text layer is positioned over each rendered canvas.
+
+Adopts `DocumentAnchorTarget`: `page`, `text-quote`, and `region` anchors resolve, and `highlights`
+paint through one `<lr-highlight-layer>` per page, stacked between the canvas and the text layer
+(canvas → highlights → text layer) so starting a text selection over a cited passage keeps working.
+Pointer activation is hit-tested at the page-wrapper level (the text layer on top intercepts most
+direct pointer events); keyboard activation reaches the highlight layer's own roving-tabindex rects
+directly, since z-stacking doesn't affect tab order. Residual: a click that *ends a text-selection
+drag* over a highlighted passage never activates it — the selection-in-progress check exists exactly
+to tell that apart from a genuine activation click.
+
+**Properties:** `src` and `name` are strings. `page: number = 1` is the one-based current page and
+`zoom: number = 1` is clamped to `0.25`–`4`. `anchorKinds` is a readonly `['page', 'text-quote',
+'region']` (this viewer's supported `LyraAnchor.kind` values for the shared anchor-target contract).
+
+**Events:**
+- `lr-render-error` — `detail: { error }` — fetching, parsing, or rendering (page canvas or text
+  layer) failed.
+- `lr-load` — `detail: { pageCount }` — the document reached `ready`. `page` is reset to `1` first.
+- `lr-page-change` — `detail: { page, pageCount }` — fired for scroll-driven page crossings as well
+  as `page` assignments and `nextPage()`/`previousPage()`/`goToPage()`.
+- `lr-zoom-change` — `detail: { zoom }`.
+- `lr-search-change` — `detail: { query, matchCount, activeIndex }` — from `search()`/`searchNext()`/
+  `searchPrevious()`/`clearSearch()`. A `src` change resets search state *silently* (no event), since
+  match page/offset coordinates only mean anything for the document they were found in.
+- `lr-highlight-activate` — `detail: { id }` — a painted highlight was clicked or activated via
+  Enter/Space. On a pointer hit-test, the last entry of `highlights` covering the point wins.
+- `lr-text-select` — `detail: { text, anchor, rects }` — a selection ended inside a page's text
+  layer. `anchor` is the computed anchor (`null` when none resolves), carrying the resolved `page`
+  when it is a `text-quote`.
+- `lr-anchor-result` — `detail: { found }` — fired after an `anchor` assignment or a
+  `scrollToAnchor()` call.
+
+**Methods:** `nextPage()`, `previousPage()`, `zoomIn()`, and `zoomOut()` update the corresponding
+controlled state within its supported range. `getPageText(page)` resolves the raw reading-order text
+of one page (per-page LRU-cached, 64 pages), rejecting on no loaded document or an out-of-range page.
+`renderPageThumbnail(page, canvas, options?)` renders `page` into a caller-owned `canvas` at
+`options.width` CSS px (default 96), devicePixelRatio-aware, resolving `false` when not ready or out
+of range. `goToPage(page)` scrolls the virtualized list to `page`, resolving `true` once mounted (or
+`false` for an out-of-range value, without changing `page`). `getOutline()` resolves the document's
+table of contents as `PdfOutlineItem[]` (`{ title, page?, children? }`), `[]` when there is none.
+`search(query)` resolves the match count across all pages (empty/whitespace query behaves like
+`clearSearch()`); `searchNext()` and `searchPrevious()` advance/step back through matches (wrapping,
+resolving `false` when there are none); `clearSearch()` clears the query, matches, and painted marks.
+
+**CSS parts:** `base`, `toolbar`, `page-indicator`, `zoom-indicator`, `pages`, `page`, `text-layer`,
+`search-match` (a `<mark>` painted into a mounted page's text layer around one search match),
+`search-match-active` (the currently active match, also carries `search-match`), `spinner`, and
+`error`. Search painting is best-effort: a page outside the virtualized render window is skipped and
+repainted once its text layer mounts, and a match spanning a text-layer span boundary that
+`Range.surroundContents()` can't wrap stays unpainted (still reachable via `searchNext()`).
+
+**Themeable custom properties:** `--lr-pdf-viewer-height` (default `var(--lr-size-24rem)`) — block
+size of the virtualized page list (`[part="pages"]`).
+
+**Optional peer dependency:** install `pdfjs-dist` with `pnpm add pdfjs-dist`. The component registers
+a lazy `application/pdf` renderer with `<lr-document-viewer>` so the PDF library is loaded only when
+a PDF is opened. Deviates from the shared degraded-render contract: an absent `pdfjs-dist` renders
+`[part="error"]` with the localized `pdfViewerMissingLibrary` message — there is no partial PDF
+rendering without it.
+
+Remote resources are capped at 25 MB; exceeding it surfaces the localized
+`documentPreviewResourceTooLarge` message instead of the PDF.

package/llms/components/lr-phone-input.md

@@ -0,0 +1,162 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/forms.md — do not edit this file. -->
+
+# `lr-phone-input`
+
+- **Import** `import '@aceshooting/lyra-ui/components/forms/phone-input/phone-input.js';` (registers the tag; side-effect import)
+- **Class** `LyraPhoneInput`, also available unregistered from `@aceshooting/lyra-ui/components/forms/phone-input/phone-input.class.js`
+- **Family** `components/forms/` — see `llms/index.md` for its siblings
+- **Optional peers** `libphonenumber-js` — see `llms/peers.md`
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-phone-input`
+
+A form-associated, country-aware telephone field. The submitted `value` is either canonical E.164
+(for example `+352621123456`) or `''` while the editable input is empty, incomplete, or invalid.
+Numbering-plan metadata and national formatting stay outside Lyra's base bundle: supply a
+synchronous `PhoneNumberAdapter`, or lazily create one from a `libphonenumber-js`-compatible module
+with `loadLibphonenumberAdapter()`. Without an adapter, already-international E.164 input still
+normalizes and validates; national input remains editable with `incomplete` validity.
+
+**Types:**
+
+```ts
+type PhoneNumberStatus = 'empty' | 'incomplete' | 'invalid' | 'valid';
+
+interface PhoneCountry {
+  code: string;         // ISO 3166-1 alpha-2
+  callingCode: string;  // no leading "+"
+  label?: string;       // overrides Intl.DisplayNames
+}
+
+interface PhoneNumberParseResult {
+  status: PhoneNumberStatus;
+  e164?: string;       // required for status: 'valid'
+  formatted?: string;  // best-effort editable display text
+  country?: string;    // detected ISO alpha-2 code
+}
+
+interface PhoneNumberAdapter {
+  readonly countries?: readonly PhoneCountry[];
+  parse(input: string, country?: string): PhoneNumberParseResult;
+}
+```
+
+**Properties:**
+
+- `value: string = ''` — canonical E.164 form/submission value. A programmatic assignment is parsed
+  and normalized synchronously but emits no user event.
+- `name: string = ''`, `disabled: boolean = false`, `required: boolean = false` — native-like
+  form-control properties supplied by `FormAssociated`; inherited disabled fieldsets are included
+  through `effectiveDisabled`.
+- `adapter?: PhoneNumberAdapter` (attribute: false) — synchronous numbering-plan parser/formatter.
+  No metadata implementation is imported by the component itself.
+- `countries: readonly PhoneCountry[] = []` (attribute: false) — explicit selector rows; takes
+  precedence over `adapter.countries`.
+- `defaultCountry: string = ''` (attribute `default-country`) — selected when `country` has not been
+  set explicitly.
+- `country: string` — current uppercase ISO alpha-2 selection; falls back to `defaultCountry`, then
+  the first explicit/adapter country. Changing the country reparses the editable number.
+- `label: string = ''`, `hint: string = ''`, `errorText: string = ''` (attribute `error-text`) —
+  visible form-field chrome; each has a matching named slot.
+- `placeholder: string = ''` — forwarded to the native telephone input.
+- `spellcheck: boolean = true`, `autocapitalize: string = ''`, `autoCorrect: string = ''`
+  (attribute `autocorrect`) — forwarded to the internal telephone input's own `spellcheck`/
+  `autocapitalize`/`autocorrect`; `spellcheck="false"` is parsed as `false` via a string-aware
+  converter (Lit's default presence-based boolean converter would otherwise treat any attribute
+  value, including the literal string `"false"`, as `true`).
+- `accessibleLabel: string | null = null` (attribute `aria-label`) — forwarded to the internal
+  telephone input. Name precedence is host `aria-label`, `phoneLabel`, visible `label`, then
+  `placeholder`.
+- `phoneLabel: string = ''` (attribute `phone-label`) — explicit accessible-name override for the
+  native telephone input.
+- `countryLabel: string = 'Select'` (attribute `country-label`) — country-selector accessible name;
+  the untouched default routes through the shared localized `select` message.
+- `incompleteText: string = 'The value is invalid.'` (attribute `incomplete-text`) — validation
+  message for dial-like input that can still become valid with more digits. The untouched default
+  routes through the shared localized `valueInvalid` message.
+- `invalidText: string = 'The value is invalid.'` (attribute `invalid-text`) — completed-invalid
+  message, localized through the same shared key while left at its default.
+- `autocomplete: string = 'tel'`, `inputmode: 'tel'|'numeric'|'text' = 'tel'`,
+  `enterkeyhint: string = ''` — forwarded to the internal `<input type="tel">`.
+- readonly `input: HTMLInputElement | undefined` — the internal native telephone input.
+- readonly `inputValue: string` — editable formatted/partial text, which remains available even when
+  canonical `value` is `''`.
+- `selectionStart`, `selectionEnd`, and `selectionDirection` — native selection getters/setters
+  forwarded to the telephone input
+- readonly `phoneStatus: PhoneNumberStatus` — current parse state. The host also reflects it through
+  `data-phone-status`.
+- readonly `form`, `labels`, `validity`, `validationMessage`, `willValidate`, and
+  `effectiveDisabled` — the shared form-associated native-like getters.
+
+**Validity:** empty + `required` sets `valueMissing`; incomplete dial-like input sets `badInput`;
+completed-invalid input sets `typeMismatch`; valid E.164 input clears all three. Partial or invalid
+text remains in `inputValue`/the native input so validation never makes a number impossible to edit,
+but its canonical submitted `value` is blank. Native validation feedback is anchored to the
+telephone input, not the adjacent country selector.
+
+**Methods:** `focus(options?)`, `blur()`, `select()`, `setSelectionRange()`, and `setRangeText()`
+forward to the native telephone input. Range-text edits reparse the number and synchronize the
+canonical value, form value, and validity.
+`setFormValue(value)`, `checkValidity()`, and `reportValidity()` come from `FormAssociated`.
+`form.reset()` restores the original declarative `value` and the default country.
+
+**Events:**
+
+- `input` — every user edit and country change.
+- `change` — native telephone-input commit timing and every country change.
+- `focus` / `blur` — bubbling, composed bridges for the internal native input's non-crossing focus
+  events.
+
+`input`/`change` detail is
+`{ value: string; inputValue: string; country: string; valid: boolean; status: PhoneNumberStatus }`.
+Programmatic property assignments and form reset/state restoration are silent.
+
+**Slots:** `label`, `hint`, `error`, `country-prefix` (optional visual before the country selector,
+such as a consumer-owned `<lr-flag>`; no flag package is imported automatically).
+
+**CSS parts:** `form-control`, `form-control-label`, `input-wrapper`, `country-prefix`,
+`country-select`, `calling-code`, `input`, `hint`, `error`.
+
+**Themeable custom properties:** shared tokens only. The phone-number input and calling code are
+deliberately `dir="ltr"`/isolated because telephone numbers are algorithmic content; surrounding
+form chrome and the country selector inherit LTR/RTL and use logical spacing/borders.
+
+**Optional peer deps:** `libphonenumber-js` is declared optional but never imported by Lyra itself.
+For full national parsing/formatting, install it in the consuming app and pass it through the
+consumer-supplied lazy loader below. Because the import expression lives in consumer code, no
+numbering metadata enters a bundle that does not opt in.
+
+```ts
+import '@aceshooting/lyra-ui/components/forms/phone-input/phone-input.js';
+import { loadLibphonenumberAdapter } from
+  '@aceshooting/lyra-ui/components/forms/phone-input/phone-input.class.js';
+
+const phone = document.querySelector('lr-phone-input');
+phone.adapter = await loadLibphonenumberAdapter(() => import('libphonenumber-js/min'));
+```
+
+```html
+<lr-phone-input
+  name="mobile"
+  label="Mobile number"
+  hint="Used only for account security"
+  default-country="LU"
+  required
+></lr-phone-input>
+```
+
+**Known gotchas:**
+
+- An adapter's `parse()` method is synchronous because it runs on every keystroke. Load any optional
+  module first, then assign the resolved adapter. Adapter exceptions degrade to the E.164-only
+  fallback rather than breaking editing.
+- A valid adapter result must include an E.164-shaped `e164`; a malformed "valid" result is treated
+  as invalid instead of entering form submission.
+- Country names use `Intl.DisplayNames` and fall back to the ISO code; set `PhoneCountry.label` for
+  a product-specific name. Calling codes are data, not derived by the component.
+- The component does not import `@aceshooting/lyra-flags`. Compose an optional flag through
+  `country-prefix` and keep it decorative when the adjacent select already announces the country.
+
+---

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

@@ -0,0 +1,70 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/charts.md — do not edit this file. -->
+
+# `lr-pie-chart`
+
+- **Import** `import '@aceshooting/lyra-ui/components/charts/chart/pie-chart.js';` (registers the tag; side-effect import)
+- **Class** `LyraPieChart`, also available unregistered from `@aceshooting/lyra-ui/components/charts/chart/pie-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-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-playback.md

@@ -0,0 +1,74 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/media.md — do not edit this file. -->
+
+# `lr-playback`
+
+- **Import** `import '@aceshooting/lyra-ui/components/media/playback/playback.js';` (registers the tag; side-effect import)
+- **Class** `LyraPlayback`, also available unregistered from `@aceshooting/lyra-ui/components/media/playback/playback.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-playback`
+
+Steps an index through `[0, length)` on a fixed interval — play/pause for time-series scrubbing.
+
+**Properties:**
+- `length: number = 0`
+- `index: number = 0`
+- `intervalMs: number = 900` (attribute `interval-ms`)
+- `playing: boolean = false` (reflected)
+- `loop: boolean = true`
+- `hidden: boolean = false` (reflected; re-declared over the native IDL property so Lit's
+  change-tracking sees it and auto-pauses on `hidden = true`)
+
+**Methods:** `play()`, `pause()`, `toggle()`, `next()`, `previous()`, `goTo(index: number)` — all
+idempotent/clamped; `length <= 1` is a no-op degenerate case. `focus(options?)` and `blur()` forward
+to the play button.
+
+**Events:** `lr-play`, `lr-pause` (no detail), `lr-step` (`detail: { index }`, fired on every
+tick and manual step); internal `focus`/`blur` are bridged as bubbling, composed host events.
+
+**Slots:** none.
+
+**CSS parts:** `base`, `play-button`, `slider`
+
+**Themeable custom properties:** `--lr-playback-icon-size` (default
+`calc(var(--lr-icon-button-size) * 0.35)` — the play/pause glyph's size; applied as the button's
+`font-size`, and the inline SVG renders at `1em`); plus shared tokens `--lr-space-s`,
+`--lr-color-border`, `--lr-color-surface`, `--lr-color-text`, `--lr-color-brand`,
+`--lr-icon-button-size` (the play button's box), `--lr-opacity-disabled` (play button/slider
+dimming at `length <= 1`), `--lr-focus-ring-*`.
+
+**Optional peer deps:** none.
+
+```html
+<lr-playback length="24" interval-ms="500"></lr-playback>
+<script>
+  const pb = document.querySelector('lr-playback');
+  pb.addEventListener('lr-step', (e) => renderFrame(e.detail.index));
+</script>
+```
+
+**Known gotchas:**
+- `index` is now re-clamped into `[0, length)` as soon as `length` shrinks (in `willUpdate()`, not
+  waiting for the next `tick()`/`goTo()`/`next()`/`previous()` call) — setting `el.length = 2` while
+  `el.index = 7` immediately pulls `index` back to `1`, and playback auto-pauses if `length` drops
+  to `<= 1` while playing (the play button and slider would otherwise both become disabled with no
+  way to stop it — both are `?disabled` whenever `length <= 1`, not just the button).
+- `intervalMs` is live-reactive mid-playback: ticking is a self-rescheduling `setTimeout` (not one
+  long-lived `setInterval`), so `intervalMs` is re-read fresh before every tick — changing
+  `interval-ms` while `playing` takes effect on the very next step instead of only after a
+  pause/play cycle.
+- `length` and `index` are normalized to finite non-negative integer counts, with `index` clamped
+  into `[0, length)`; fractional, negative, `NaN`, infinite, and oversized values cannot poison
+  end conditions or the slider.
+- `interval-ms` is clamped to the 16ms floor and the browser's finite timer ceiling: a non-finite or
+  lower value ticks at 16ms, while an oversized value uses the timer ceiling. Each distinct invalid
+  value is warned once (deduplicated per value, not a single once-ever flag).
+- No `aria-valuetext`/visible "N of M" position label on the range input.
+- Calling `play()`/`pause()` programmatically (not via the button) gives no `aria-live`
+  announcement of the Play/Pause state change.
+
+---

package/llms/components/lr-polar-area-chart.md

@@ -0,0 +1,70 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/charts.md — do not edit this file. -->
+
+# `lr-polar-area-chart`
+
+- **Import** `import '@aceshooting/lyra-ui/components/charts/chart/polar-area-chart.js';` (registers the tag; side-effect import)
+- **Class** `LyraPolarAreaChart`, also available unregistered from `@aceshooting/lyra-ui/components/charts/chart/polar-area-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-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-policy-summary.md

@@ -0,0 +1,33 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/agent-tools.md — do not edit this file. -->
+
+# `lr-policy-summary`
+
+- **Import** `import '@aceshooting/lyra-ui/components/agent-tools/policy-summary/policy-summary.js';` (registers the tag; side-effect import)
+- **Class** `LyraPolicySummary`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/policy-summary/policy-summary.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-policy-summary`
+
+Read-only list of guardrail, permission, privacy, and tool-policy decisions with accessible
+allow, deny, or needs-review explanations.
+
+**Properties:** `decisions: PolicyDecision[] = []` (attribute: false) — `PolicyDecision { id: string;
+category: PolicyDecisionCategory; label: string; state: PolicyDecisionState; explanation: string;
+detail?: string }`, with `PolicyDecisionCategory = 'guardrail' | 'permission' | 'privacy' | 'tool'`
+and `PolicyDecisionState = 'allow' | 'deny' | 'needs-review'` (all three exported here). `label` is
+host-supplied data rendered as-is, never localized (a rule name, or a tool name for `category:
+'tool'`). `explanation` is an **always-visible** plain-text reason — `state` is never conveyed by
+color alone; it tones the badge and callout as `allow` → success, `deny` → danger, `needs-review` →
+warning. `detail` is optional richer evidence (matched rule text, policy id) revealed through
+progressive disclosure. Controlled and never mutated — pass a new array to update it.
+
+**Events:** none. Read-only and display-only: this component never mutates a decision and offers no
+resolve/acknowledge action — see `lr-tool-approval-dialog`/`lr-confirm-bar` for a real approve/deny
+gate.
+
+**CSS parts:** `base`, `empty`, `summary`, `count`, `state-badge`,
+`list`, `decision`, `decision-header`, `category`, `label`, `detail`, `explanation`.