@aceshooting/lyra-ui 7.6.0 → 7.7.0

package/llms/components/lr-chart.md

@@ -6,7 +6,7 @@
 - **Class** `LyraChart`, also available unregistered from `@aceshooting/lyra-ui/components/charts/chart/chart.class.js`
 - **Family** `components/charts/` — see `llms/index.md` for its siblings
 - **Optional peers** `chart.js`, `chartjs-plugin-datalabels`, `chartjs-plugin-zoom` — see `llms/peers.md`
-- **Themeable via** 7 parts, 7 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 11 parts, 7 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---
@@ -24,9 +24,12 @@ Chart.js wrapper every other `lr-*-chart` tag subclasses; supports both a simpli
   unknown runtime attribute/property values fall back to `line` before reaching Chart.js
 - `labels: string[] = []` (attribute: false)
 - `datasets: Series[] = []` (attribute: false) — `Series { label: string; data?: (number|null)[];
-  points?: {x,y,label?}[]; color?: string|string[]; fill?: boolean; width?: number; dash?: boolean;
+  points?: ChartPoint[]; color?: string|string[]; fill?: boolean; width?: number; dash?: boolean;
   noTooltip?: boolean; axis?: 'y'|'y2'; pointColors?: string[]; pointRadius?: number|number[];
-  segmentColors?: string[]; type?: 'line'|'bar' }`
+  segmentColors?: string[]; type?: 'line'|'bar' }`. Both the package root and granular chart entry
+  export `ChartPoint { x: number; y: number; r?: number; label?: string }`: `r` is the bubble
+  radius, and the optional per-point `label` is retained by events, CSV export, keyboard
+  announcements, generated summaries, and the accessible table.
   - `pointRadius` takes a single number (applied to every point) **or** an array matching `data`'s
     length that sizes each point independently — passed straight through to Chart.js, which
     supports both natively. Useful for emphasizing a single outlier or the latest reading without
@@ -37,7 +40,11 @@ Chart.js wrapper every other `lr-*-chart` tag subclasses; supports both a simpli
     `segment.borderColor` scriptable option, so it is only meaningful for line-type series.
     Typical use is threshold/anomaly banding along one line. A series that omits it (or passes an
     empty array) emits no `segment` key at all, leaving line rendering exactly as before.
-- `legend: boolean = false`
+- `legend: boolean = false` — renders a wrapping DOM legend whose keyboard-operable buttons toggle
+  dataset visibility. The DOM surface preserves long public labels that a canvas legend would clip.
+  Its pressed state honors an effective dataset's declarative `hidden` value before Chart.js is
+  ready and across chart type/plugin rebuilds, while an in-place redraw preserves an explicit
+  legend-button toggle.
 - `legendPosition: LyraChartLegendPosition = 'top'` (attribute `legend-position`) — places the
   legend at `top`, `right`, `bottom`, or `left`; `auto` chooses right above 480px and bottom below
   that allocation width
@@ -75,6 +82,11 @@ Chart.js wrapper every other `lr-*-chart` tag subclasses; supports both a simpli
 - `config?: Partial<ChartConfiguration>` (attribute: false) — deep-merged over the generated
   config; any nested key wins without clobbering sibling generated keys. This is the raw Chart.js
   escape hatch, so a caller-supplied `config.type` is passed through rather than normalized.
+  Explicit `config.data.labels` and `config.data.datasets` arrays are authoritative independently:
+  an omitted member still comes from the simplified `labels`/`datasets` properties, while an
+  explicit array replaces that generated member rather than concatenating with it. This effective
+  model drives canvas rendering, `appendData()`, export, the accessible name/summary, keyboard
+  navigation and activation events, the DOM legend, and the generated fallback table.
 - `accessibleLabel: string = ''` (attribute `accessible-label`) — canvas name override; a host
   `aria-label` has highest precedence
 - `accessibleDescription: string = ''` (attribute `accessible-description`) — overrides the
@@ -85,15 +97,23 @@ Chart.js wrapper every other `lr-*-chart` tag subclasses; supports both a simpli
   canvas-local coordinates (`top`, `left`, `right`, `bottom`, `width`, `height`), when a chart is
   drawn
 - `appendData(label, values, maxPoints?)` — appends one aligned numeric category and optionally
-  keeps only the newest `maxPoints`; point-based scatter/bubble series are left unchanged
+  keeps only the newest `maxPoints`. Each labels/datasets member is written back to the surface
+  that owns it: an explicitly overridden `config.data` member stays in `config`, while an omitted
+  member continues through the simplified property and retains its generated Chart.js styling.
+  Point-based scatter/bubble series are left unchanged because appending their x/y/r coordinates
+  needs a richer caller-defined contract.
 
 **Methods:** `resetZoom()` resets any active zoom/pan to the original view. `refreshTheme()` forces
 a redraw so the `--lr-chart-*` tokens below are re-read from the current computed style. A
 built-in `ThemeWatcher` now calls this automatically when `prefers-color-scheme` flips or an
 ancestor's `class`/`style`/`data-theme`/`data-color-scheme` attribute mutates — the most common
 theme-toggle mechanisms — so a consumer rarely needs to call it by hand; it remains public as the
-escape hatch for theme changes those signals can't observe. `exportData('csv' | 'png')` returns a
-spreadsheet-safe CSV snapshot or the current PNG data URL when Chart.js is loaded.
+escape hatch for theme changes those signals can't observe. Canvas redraw remains visibility-gated;
+when a DOM legend is present its computed swatch colors are refreshed too.
+`exportData('csv' | 'png')` returns a spreadsheet-safe CSV snapshot or the current PNG data URL
+when Chart.js is loaded. Numeric datasets retain the compact one-column-per-series CSV shape.
+Point datasets expand into `<series> x`, `<series> y`, and, when present, `<series> r` and
+`<series> label` columns so radius and per-point labels are not flattened away.
 
 The instance method `seriesPalette(): string[]` resolves the categorical series ramp
 (`--lr-color-chart-1..8`) through `getComputedStyle` and returns the concrete, theme-aware colors —
@@ -119,20 +139,26 @@ const series = [
 ```
 
 **Events:** `lr-zoom` (`detail: { zoomed: boolean }`, fired on zoom-complete and on
-`resetZoom()`), `lr-point-click` (fired when a click lands on, or nearest to — intersect-only —
-a data point/segment, for any chart type, not just bar; `detail: { datasetIndex: number, index:
-number, label: string | undefined, value: unknown }`)
+`resetZoom()`), `lr-point-click` (fired when pointer input lands on an intersecting data
+point/segment, when a generated-table value is activated, or when Enter/Space activates the
+keyboard-current canvas datum; `detail: { datasetIndex: number, index: number, label: string |
+undefined, value: unknown }`). For scatter/bubble points, `label` prefers the per-point label and
+`value` is the complete `ChartPoint`, including optional `r` and `label`.
 
 **Slots:** `data-table` — an optional consumer-provided accessible table alternative; `center` —
 optional overlay content positioned at the chart area's center, useful for doughnut and pie totals.
 
-**CSS parts:** `base`, `canvas`, `reset-zoom-button`, `description`, `data-table`, `center` (the
-chart-area-centered wrapper for the `center` slot), `error` (`role="alert"` message rendered in
-place of `canvas` when the optional `chart.js` peer dependency fails to load)
+**CSS parts:** `base`, `plot` (the fixed-height canvas/overlay region), `canvas`, `legend` (the
+wrapping DOM legend), `legend-item` (a dataset-visibility button), `legend-swatch`,
+`reset-zoom-button`, `description`, `data-table`, `center` (the chart-area-centered wrapper for the
+`center` slot), `error` (`role="alert"` message rendered in place of `canvas` when the optional
+`chart.js` peer dependency fails to load)
 
 **Themeable custom properties:** `--lr-chart-height` (set programmatically on the host from the
-`height` property — must be read from the host, not a shadow-tree descendant, since custom
-properties only cascade downward); `--lr-chart-grid-color` (default `var(--lr-color-border)`),
+`height` property; sizes the `plot` region and the host's minimum block size, while a visible table
+or wrapping legend grows the host in normal flow — it must be read from the host, not a shadow-tree
+descendant, since custom properties only cascade downward);
+`--lr-chart-grid-color` (default `var(--lr-color-border)`),
 `--lr-chart-tick-color` (default `var(--lr-color-text-quiet)`), `--lr-chart-legend-color`
 (default `var(--lr-color-text)`), `--lr-chart-tooltip-bg` (default `var(--lr-color-surface)`),
 `--lr-chart-tooltip-text` (default `var(--lr-color-text)`) — each resolved fresh via
@@ -168,9 +194,14 @@ subset actually used.
   property values fall back to `line`. Each typed `lr-*-chart` subclass (e.g.
   `llms/components/lr-bar-chart.md`) locks its *own* `type` via a real prototype accessor — a
   genuine runtime lock, not just a compile-time default.
-- a built-in `ThemeWatcher` auto-retheme an already-drawn chart when `prefers-color-scheme` flips or
-  an ancestor's `class`/`style`/`data-theme`/`data-color-scheme` attribute mutates (coalesced to one
-  redraw). `refreshTheme()` stays public for out-of-band theme changes those signals can't observe.
+- a built-in `ThemeWatcher` automatically rethemes an already-drawn chart when
+  `prefers-color-scheme` flips or an ancestor's `class`/`style`/`data-theme`/`data-color-scheme`
+  attribute mutates (coalesced to one redraw). `refreshTheme()` stays public for out-of-band theme
+  changes those signals can't observe.
+- the focusable canvas is an interactive `application`, not a static image: Arrow keys move through
+  finite data, Home/End jump to the endpoints, and Enter/Space activates the current datum. Its
+  localized `aria-roledescription` identifies the application as a chart; the generated table is
+  the non-canvas alternative.
 - generated `scales` are keyed off the *effective* type (`config.type` ?? `type`, see
   `effectiveType()`) and are type-appropriate: no scale at all for `type="pie"`/`"doughnut"` (true of
   `<lr-chart type="pie">` directly, not just the `lr-pie-chart`/`lr-doughnut-chart` subclasses),
@@ -196,11 +227,14 @@ subset actually used.
   single redraw fires once it re-enters the viewport). Independently, `updated()` only reaches
   Chart.js when at least one of `type`, `labels`, `datasets`, `legend`, `legendPosition`, the
   internal resolved auto legend position, `valueFormatter`, `area`, `height`, `xLabel`, `yLabel`,
-  `y2Label`, `beginAtZero`, `horizontal`, `stacked`, `config`, `zoom`, `locale`, `strings`, or the
-  internal loading state actually changed in that update (so an unrelated property/state update, or
-  a bare `requestUpdate()`, draws nothing). `refreshTheme()` calls `draw()` directly and is
-  unaffected by either gate — it always redraws, since a theme change isn't reflected in any tracked
-  property.
+  `y2Label`, `beginAtZero`, `horizontal`, `stacked`, `dataLabels`, `stackTotals`, `config`, `zoom`,
+  `locale`, `strings`, or the internal loading state actually changed in that update (so an
+  unrelated property/state update, or a bare `requestUpdate()`, draws nothing). Resize callbacks
+  ignore unchanged inline sizes and coalesce into one animation-frame task; a responsive legend
+  position change and its reactive update share that same single redraw. `refreshTheme()`, resize,
+  optional-plugin completion, and histogram data changes all use the same connected/visible gate.
+  A theme refresh may still rerender the cheap DOM legend while off-screen so its computed swatches
+  do not go stale, but it does not repaint the canvas there.
 - Chart.js receives `effectiveLocale`; generated summary values use the same locale. Cartesian y/y2
   axes swap logical sides under RTL, and host `aria-label` is forwarded to the canvas and data-table
   caption.

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

@@ -168,7 +168,9 @@ library-wide `--lr-color-text` token. Left unset, rendering is unchanged. Otherw
 Since CSS alone can't parameterize `:nth-child` on a runtime prop, `<lr-chip-group>` reaches
 directly into the light DOM and sets each excess child's own `hidden` property once `max-visible` is
 exceeded — the same approach `<lr-split>` uses to set each panel's inline `flex`/`order`, rather
-than a stylesheet-only solution.
+than a stylesheet-only solution. It observes live author changes to each managed child's `hidden`
+state and restores the latest author-owned value when ownership ends or the group disconnects;
+reconnecting reapplies the current collapsed state.
 
 **Known gotchas:**
 - `<lr-chip>`'s accessible remove-button label ("Remove {text}") is computed only from the default

package/llms/components/lr-chip.md

@@ -168,7 +168,9 @@ library-wide `--lr-color-text` token. Left unset, rendering is unchanged. Otherw
 Since CSS alone can't parameterize `:nth-child` on a runtime prop, `<lr-chip-group>` reaches
 directly into the light DOM and sets each excess child's own `hidden` property once `max-visible` is
 exceeded — the same approach `<lr-split>` uses to set each panel's inline `flex`/`order`, rather
-than a stylesheet-only solution.
+than a stylesheet-only solution. It observes live author changes to each managed child's `hidden`
+state and restores the latest author-owned value when ownership ends or the group disconnects;
+reconnecting reapplies the current collapsed state.
 
 **Known gotchas:**
 - `<lr-chip>`'s accessible remove-button label ("Remove {text}") is computed only from the default

package/llms/components/lr-citation-badge.md

@@ -28,8 +28,9 @@ anything about `<lr-source-card>`, it only carries the id through its event deta
   echoed back verbatim in both events; never read or validated by this component.
 - `href: string = ''` — optional direct link target for the citation's source, carried into
   `lr-citation-open`'s detail as-is; this component never navigates.
-- `label: string = ''` — overrides the computed accessible name. The built-in citation/status
-  summary is a complete localized template; a host `aria-label` has highest precedence.
+- `label: string = ''` — adds caller-supplied context to the localized citation name while retaining
+  the visible citation number (for example, `"Citation 3, Annual report"`). A host `aria-label`
+  remains the exact highest-precedence override.
 
 **Events:**
 - `lr-citation-activate` (`detail: { sourceId: string; index: number }`) — fires on click, or on

package/llms/components/lr-code-editor.md

@@ -28,7 +28,7 @@ optional line-number gutter. No syntax highlighting: `language` is metadata only
   `placeholder: string = ''`
 - `readonly: boolean = false` (reflected) — also disables Tab indentation
 - `resize: 'none' | 'both' | 'horizontal' | 'vertical' = 'both'` — written as the textarea's inline
-  `resize`
+  `resize`; an invalid runtime value falls back to `'both'`
 - `wrap: 'off' | 'soft' | 'hard' = 'off'` — native textarea wrapping; `'off'` (the default) makes
   the `editor` part the single horizontal scroll viewport
 - `spellcheck: boolean = false` — off by default for code, and parsed with a string-aware converter

package/llms/components/lr-combobox.md

@@ -87,6 +87,8 @@ number; accessibleLabel?: string; data?: unknown; dotColor?: string; group?: str
 boolean }` — the row shape used by the async `source` path. `icon` renders as a decorative leading
 visual, `badge` as trailing metadata, `accessibleLabel` can provide richer spoken text than the
 visible label, and `data` is retained without being rendered for retrieval through `selectedRows`.
+`dotColor` accepts a valid CSS `color`; invalid values, declaration-breaking input, and `url()`
+render a transparent dot.
 The light-DOM `<lr-option>` path normalizes its supported label/sub/dot/group fields to the same
 internal row model.
 
@@ -109,7 +111,6 @@ selection. It is the supported way to read that text; reaching into the shadow r
 carrying different strings. It fires for user input only: picking a row, the clear button,
 `form.reset()`, dismissing the listbox, a programmatic `value` write, and `setRangeText()` all blank
 the filter silently, mirroring how `<lr-input>`'s `lr-input` only reports user edits.
-
 `lr-show` and `lr-hide` report listbox visibility transitions.
 The internal input's `focus` and `blur` are re-dispatched as bubbling, composed host events.
 
@@ -212,9 +213,12 @@ box visibly (nothing is clipped or made unreachable), so leave it unset there.
   visible label)
 - `sub: string = ''` (optional secondary line rendered under the label, e.g. a status/date summary)
 - `dotColor: string = ''` (attribute `dot-color` — optional CSS color for a small leading status
-  dot, any valid CSS color)
+  dot; invalid values, declaration-breaking input, and `url()` render the dot transparently)
 - `label` is a **read-only getter**: explicit `label` attribute wins, else trimmed `textContent`.
 
+**Events:** `lr-option-change` — bubbles when the option's label or selectable data changes so
+its parent `lr-combobox` or `lr-select` can refresh its normalized option rows.
+
 ```html
 <lr-combobox id="cb" label="Country" placeholder="Search…" with-clear>
   <lr-option value="fr">France</lr-option>

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

@@ -6,7 +6,7 @@
 - **Class** `LyraComparePanel`, also available unregistered from `@aceshooting/lyra-ui/components/agent-tools/compare-panel/compare-panel.class.js`
 - **Family** `components/agent-tools/` — see `llms/index.md` for its siblings
 - **Optional peers** none
-- **Themeable via** 9 parts, 1 custom property — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 9 parts, 4 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---
@@ -29,6 +29,8 @@ scroll position. `disabled: boolean = false` (reflected) disables every vote but
 output), and `prompt` (optional shared-input header above both panes).
 
 **Events:** `lr-vote` — `detail: { choice: 'a' | 'b' | 'tie' | 'both-bad'; itemId: string }`.
+This is a cancelable veto point emitted before `vote` changes; call `preventDefault()` to preserve
+the prior vote.
 
 **CSS parts:** `base` (the outer wrapper), `prompt` (the optional prompt header, hidden when the
 `prompt` slot is empty), `panes` (the row, or under 640px column, wrapping both panes), `pane-a`,
@@ -37,4 +39,8 @@ output), and `prompt` (optional shared-input header above both panes).
 internal vote-announcement live region).
 
 **Themeable custom properties:** `--lr-compare-panel-max-height` (default `var(--lr-size-24rem)`) —
-cap on each pane's scroll region before it scrolls internally.
+cap on each pane's scroll region before it scrolls internally;
+`--lr-compare-panel-selected-background` (default `var(--lr-color-brand-quiet)`),
+`--lr-compare-panel-selected-border-color` (default `var(--lr-color-brand)`), and
+`--lr-compare-panel-selected-color` (default `var(--lr-color-brand)`) style the selected vote
+button without changing shared brand tokens.

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

@@ -21,8 +21,9 @@ label when `FN` is absent).
 Remote resources are capped at 25 MB; exceeding it surfaces the localized
 `documentPreviewResourceTooLarge` message instead of the contacts.
 
-**Properties:** `src`, `name`, and `maxHeight` (attribute `max-height`) are strings. A host
-`aria-label` takes precedence over `name`. `highlights`, `activeHighlightId`, `anchor`, and
+**Properties:** `src`, `name`, and `maxHeight` (attribute `max-height`) are strings; invalid CSS
+`max-height` values, declaration breaks, and `url()` are ignored. A host `aria-label` takes
+precedence over `name`. `highlights`, `activeHighlightId`, `anchor`, and
 `anchorKinds` (`['text-quote', 'fragment']`) provide the shared text-viewer contract.
 
 **Methods:** `search(query)`, `searchNext()`, `searchPrevious()`, `clearSearch()`, and

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

@@ -49,6 +49,8 @@ buttons, this has no code/JSON content model to adopt just to reuse the copy aff
 - best-effort clipboard write: `navigator.clipboard` is absent in insecure contexts/older browsers,
   and some engines throw synchronously rather than rejecting — either way `lr-copy` still fires
   with the intended text so a consumer can always show its own confirmation/fallback UI.
+- Changing `value` clears any in-progress "Copied" feedback immediately, so the confirmation can
+  never describe stale text.
 
 **Additional API surface:**
 

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

@@ -23,9 +23,9 @@ row/column into view via the virtualized list's `active-id`. `highlights` paint
 **Properties:** `src` and `name` are strings. `hasHeaderRow: boolean = true` (attribute
 `has-header-row`) controls whether the first parsed row is rendered as a sticky header.
 `maxHeight: string = ''` (attribute `max-height`) is a CSS length that caps the scrollable body —
-setting it writes `--lr-csv-viewer-max-height` inline on `[part="base"]`. `anchorKinds` is a
-readonly `['cell-range']` (this viewer's supported `LyraAnchor.kind` values for the shared
-anchor-target contract).
+setting it writes `--lr-csv-viewer-max-height` inline on `[part="base"]`; invalid CSS `max-height`
+values, declaration breaks, and `url()` are ignored. `anchorKinds` is a readonly `['cell-range']`
+(this viewer's supported `LyraAnchor.kind` values for the shared anchor-target contract).
 
 **Methods:** `search(query)` resolves the match count via a case-insensitive substring match over
 the same stringified cell values `cell()` renders, ordered row then column (empty/whitespace query

package/llms/components/lr-dashboard-grid.md

@@ -6,7 +6,7 @@
 - **Class** `LyraDashboardGrid`, also available unregistered from `@aceshooting/lyra-ui/components/layout/dashboard-grid/dashboard-grid.class.js`
 - **Family** `components/layout/` — see `llms/index.md` for its siblings
 - **Optional peers** none
-- **Themeable via** 5 parts, 5 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 5 parts, 6 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---
@@ -40,3 +40,4 @@ draggable/resizable target; set it to `transparent` to opt out of the hover trea
 **Additional API surface:**
 
 - `--lr-dashboard-grid-collision-outline-color` — Outline color of a cell whose current drag/resize preview collides with another cell. Default: `var(--lr-color-danger)`.
+- `--lr-dashboard-grid-interaction-shadow` — Box shadow applied during a cell drag or resize. Default: `var(--lr-shadow)`.

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

@@ -24,9 +24,10 @@ is never part of the virtualized body); `scrollToAnchor()` scrolls the addressed
 the virtualized list's `active-id`. `highlights` paint as a `part="cell-highlight"` cell wrapping a
 focusable `part="cell-highlight-action"` native button, keeping the ARIA table tree intact.
 
-**Properties:** `src`, `name`, and `maxHeight` (attribute `max-height`) are strings. `anchorKinds` is
-a readonly `['cell-range']` (this viewer's supported `LyraAnchor.kind` values for the shared
-anchor-target contract).
+**Properties:** `src`, `name`, and `maxHeight` (attribute `max-height`) are strings; invalid CSS
+`max-height` values, declaration breaks, and `url()` are ignored. `anchorKinds` is a readonly
+`['cell-range']` (this viewer's supported `LyraAnchor.kind` values for the shared anchor-target
+contract).
 
 **Methods:** `search(query)` resolves the match count via a case-insensitive substring search over
 every body cell's raw string value, ordered row then column (empty/whitespace query behaves like

package/llms/components/lr-dialog.md

@@ -39,8 +39,9 @@ hand-building that chrome isn't worth it.
 
 Also settable as a plain `aria-label` attribute (not a public JS property): overrides the panel's
 computed accessible name outright, winning over every other source below (a slotted heading,
-`heading`, `label`) — matching `<lr-date-input>`'s `accessibleLabel` pattern. Left unset, the
-existing three-tier fallback below is unchanged.
+`heading`, `label`) — matching `<lr-date-input>`'s `accessibleLabel` pattern. It changes naming
+only: a `heading` property still renders its visible header chrome. Left unset, the existing
+three-tier fallback below is unchanged.
 
 **Methods:** `close(reason: DialogCloseReason = 'api'): void` — closes the dialog, emits
 `lr-dialog-close` with `reason`, and returns focus to whatever had it right before the dialog
@@ -52,8 +53,10 @@ own `close()` (a consumer's own cleanup code, a parent re-render that drops it);
 whatever a caller passes (e.g. a footer Cancel button calling `dlg.close('cancel')`, or `confirm()`'s
 own `'confirm'`/`'cancel'`).
 
-**Events:** `lr-dialog-close` (`detail: DialogCloseReason`) — fired on every dismissal path
-(Escape, backdrop click, any `close()` call, or an `'unmount'` removal as above).
+**Events:** `lr-dialog-close` (`detail: DialogCloseReason`) — a cancelable event fired on every
+dismissal path (Escape, backdrop click, the built-in close button, any `close()` call, or an
+`'unmount'` removal as above). Calling `preventDefault()` keeps a connected dialog open for every
+dismissal path; `'unmount'` cannot practically be vetoed because removal already happened.
 
 **Stacking:** participates in the shared per-document overlay stack described above. A dialog can be
 stacked with another dialog or any other modal family; only the visually topmost overlay receives
@@ -103,19 +106,20 @@ clipped; the viewport is still a hard limit either way), plus shared tokens `--l
 
 Accessible name / visible header, in priority order: (0) if the host element itself has an
 `aria-label` attribute set, its value becomes `aria-label` on the panel outright, overriding every
-source below (including a slotted heading) and suppressing the visible header/`heading` row and the
-sr-only `label` element from rendering at all — the standard ARIA convention for a consumer that
-wants full control over the announced name regardless of whatever `heading`/`label` props are also
-set; (1) otherwise, if a heading element (`h1`–`h6` or
+source below (including a slotted heading) while leaving visible `heading` chrome intact — the
+standard ARIA convention for a consumer that wants full control over the announced name regardless
+of whatever `heading`/`label` props are also set; (1) otherwise, if a heading element (`h1`–`h6` or
 `[role="heading"]`) is a *direct child* (not inside `slot="footer"`), its text content becomes
 `aria-label` on the panel — takes priority over `heading` below so an existing consumer that already
 slots its own heading keeps rendering it exactly as before; (2) otherwise, when `heading` is set, a
 visible header row (`[part="header"]`) renders containing that text (`[part="heading"]`), which
 becomes the `aria-labelledby` target; (3) otherwise, when `label` is set, an invisible (`.sr-only`,
 exposed as the `label` part) element carrying that text is rendered inside the panel and
-`aria-labelledby` points at it instead. Only one of cases 2/3 ever renders at a time. `label` itself
-never renders visible chrome on its own — `::part(label)` can be restyled to make the sr-only text
-visible, or `heading` can be set instead, for visible chrome without slotting a real heading element.
+`aria-labelledby` points at it instead. Only one of cases 2/3 supplies `aria-labelledby` at a time;
+case 0 can coexist with case 2's visible heading, but its explicit `aria-label` remains the name.
+`label` itself never renders visible chrome on its own — `::part(label)` can be restyled to make the
+sr-only text visible, or `heading` can be set instead, for visible chrome without slotting a real
+heading element.
 The slotted-heading case (1) deliberately uses `aria-label` (a copied string) rather than
 `aria-labelledby` pointing at the heading's `id`, because the heading is light-DOM content while
 `[part="panel"]` lives in shadow DOM and an ID-reference attribute can't resolve across that
@@ -125,9 +129,8 @@ root it labels.
 **Known gotchas:**
 - `role="dialog"`/`aria-modal="true"` are only present on `[part="panel"]` while `open` is `true` —
   inspecting closed markup won't show them.
-- Heading detection only rescans on `slotchange`, not on every render — mutating an already-slotted
-  heading's `textContent` in place (rather than replacing the node) won't retroactively update
-  `aria-label`; set `label` instead for a title that needs to change live.
+- Heading detection observes child, subtree, and character-data changes, so mutating an
+  already-slotted direct heading's text updates the copied panel `aria-label` live.
 - Only *direct* children are scanned for a heading — one nested several layers deep, or inside a
   slotted custom element's own shadow root, is left to the consumer to label explicitly via `label`.
 - A reconnect that preserves the same element instance (e.g. a drag-and-drop reparent) resumes its
@@ -174,7 +177,8 @@ used is still a `--lr-*` token reference, never a raw literal.
 - Every dismissal path (confirm button, cancel button, Escape, backdrop click) funnels through
   `<lr-dialog>`'s own `close()`/`lr-dialog-close` event, so there is exactly one place that
   resolves the promise and tears the dialog down — a consumer never needs to (and shouldn't) call
-  `.remove()` itself.
+  `.remove()` itself. Because the close event is cancelable, `confirm()` waits through the full
+  dispatch and remains pending/mounted when a listener calls `preventDefault()`.
 - The neutral confirm button pairs `--lr-color-on-brand` with `--lr-color-brand`; the danger
   tone pairs `--lr-color-on-danger` with `--lr-color-danger`. Each token chains through Web
   Awesome's matching `*-on-loud` semantic role and has contrast-tested standalone light/dark

package/llms/components/lr-diff-view.md

@@ -87,6 +87,7 @@ consumer can compute or unit-test the same alignment without instantiating the e
   explicit performance-risk opt-out.
 - the computed `diffOps` state is cached and recomputed only when `oldText`, `newText`, or
   `maxLines` changes. Copy-confirmation and other unrelated renders reuse the cached alignment.
+- Changing either `oldText` or `newText` clears any in-progress "Copied" feedback immediately.
 
 **Additional API surface:**
 

package/llms/components/lr-divider.md

@@ -13,7 +13,8 @@
 
 ## `lr-divider`
 
-A semantic separator: renders `<hr part="base" role="separator" aria-orientation="…">`.
+A semantic separator: renders `<hr part="base" role="separator" aria-orientation="…">`. A host
+`aria-label` is forwarded to that inner semantic owner.
 
 **Properties:** `orientation: 'horizontal' | 'vertical' = 'horizontal'` (reflected).
 

package/llms/components/lr-document-preview.md

@@ -65,13 +65,15 @@ image path — and the generic fallback simply omits `[part="download-link"]` en
   `status="error"`.
 - `maxHeight: string = ''` (attribute `max-height`) — a CSS length (e.g. `"24rem"`); once set,
   `[part="body"]` scrolls internally past this height instead of growing the page — same contract as
-  `lr-json-viewer`'s identically-named prop.
+  `lr-json-viewer`'s identically-named prop. Invalid CSS `max-height` values, declaration breaks,
+  and `url()` are ignored, leaving the stylesheet token in control.
 - `zoomable: boolean = false` (reflected) — wraps the rendered image (image format only) in an
   internal `<lr-zoomable-frame>`. `false` (the default) preserves the exact pre-`zoomable` DOM — an
   inline thumbnail (e.g. in a chat stream) must not unexpectedly grow a focusable zoom-chrome
   viewport; an inspection surface opts in.
 - `highlights: LyraHighlight[] = []` (attribute: false) — display-only `region` highlights painted
-  over the image-format preview; ignored for the `text`/`generic` formats.
+  over the image-format preview; ignored for the `text`/`generic` formats. A rectangle renders only
+  when `x`/`y`/`width`/`height` are finite numbers and both dimensions are nonnegative.
 - `activeHighlightId: string | null = null` (attribute `active-highlight-id`) — the `highlights`
   entry, if any, currently treated as active (`data-active` on its `region-highlight`).
 - `anchorKinds` is a readonly `['region']` (this viewer's supported `LyraAnchor.kind` values for the

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

@@ -23,8 +23,10 @@ type. First-party invention.
 - `mimeType: string = ''` (attribute `mime-type`) — MIME type used for exact renderer dispatch.
 - `src: string = ''` — source URL passed to the selected renderer or the fallback preview.
 - `registry?: DocumentRendererRegistry` (attribute: false) — optional per-instance registry override;
-  the module-level registry is used when unset.
-- `alt: string = ''` — media alt text forwarded to the resolved renderer, for image-like renderers.
+  the module-level registry is used when unset. A throwing consumer matcher or renderer is
+  contained as the localized error state rather than escaping the update.
+- `alt?: string` — media alt text forwarded to the resolved renderer, for image-like renderers.
+  Unset lets the renderer derive its fallback; an explicit `''` preserves decorative media.
 - `anchor: LyraAnchor | string | null = null` (attribute: false) — declarative scroll-to-anchor
   target forwarded to the resolved renderer; a string is a highlight id in `highlights`.
   `hasChanged: () => true`, so re-assigning the same value (e.g. re-clicking the same citation
@@ -47,6 +49,7 @@ type. First-party invention.
   (a highlight id) counts as supported by any renderer declaring at least one anchor kind.
 
 **CSS parts:** `body` — wrapper around the active renderer, loading/error state, or fallback preview;
+it renders explicit `aria-busy="true"|"false"`, and the loading text itself owns `role="status"`;
 `download-link` — the native download action, rendered when `src` passes Lyra's safe-link policy.
 
 **Themeable custom properties:** `--lr-document-viewer-max-height` (default `70vh`) — maximum block
@@ -84,3 +87,6 @@ registerDocumentRenderer('application/x-example', {
 
 When no renderer matches, the viewer renders `<lr-document-preview>`, which handles text and images
 inline and provides a safe generic fallback for other formats.
+
+If a consumer matcher/renderer throws while an anchor is pending, the viewer renders a localized
+`role="alert"` and emits exactly one `lr-anchor-result` with `{ found: false }`.

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

@@ -6,7 +6,7 @@
 - **Class** `LyraDocxViewer`, also available unregistered from `@aceshooting/lyra-ui/components/viewers/docx-viewer/docx-viewer.class.js`
 - **Family** `components/viewers/` — see `llms/index.md` for its siblings
 - **Optional peers** `dompurify`, `mammoth` — see `llms/peers.md`
-- **Themeable via** 8 parts, 11 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 10 parts, 11 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
 ---
@@ -22,10 +22,13 @@ hatch: if `dompurify` is unavailable, rendering is blocked even when Mammoth con
 Every rendered heading's slug (the same GitHub-slugger-style algorithm `<lr-markdown>` uses) is
 stamped as its `id` and cached into `getHeadingTree()`'s document-ordered outline. Adopts
 `DocumentAnchorTarget`: `fragment` anchors resolve against that outline, `text-quote` anchors via
-the shared quote-scoping helpers; `highlights` re-resolve by quote after every render.
+the shared quote-scoping helpers; `highlights` re-resolve by quote after every render. Native
+keyboard actions are exposed only for highlights whose quote resolves in the currently loaded
+document; unresolved highlights and idle/loading/error states never expose an enabled no-op.
 
 **Properties:** `src`, `name`, and `maxHeight` (attribute `max-height`) are strings. `maxHeight` caps
-the scrollable document body. `anchorKinds` is a readonly `['fragment', 'text-quote']` (this
+the scrollable document body; invalid CSS `max-height` values, declaration breaks, and `url()` are
+ignored. `anchorKinds` is a readonly `['fragment', 'text-quote']` (this
 viewer's supported `LyraAnchor.kind` values for the shared anchor-target contract).
 
 **Methods:** `getHeadingTree()` returns the document-ordered outline as `DocxHeadingItem[]` (`{ id,
@@ -38,14 +41,17 @@ painted marks.
 **Events:** `lr-render-error` with `detail.error` when fetching, conversion, sanitization, or a
 non-fatal Mammoth conversion message occurs. `lr-search-change` (`detail: { query, matchCount,
 activeIndex }`) — from `search()`/`searchNext()`/`searchPrevious()`/`clearSearch()`.
-`lr-highlight-activate` (`detail: { id }`) — a painted `text-quote` highlight was clicked.
+`lr-highlight-activate` (`detail: { id }`) — a painted `text-quote` highlight was clicked or its
+resolved keyboard action was activated.
 `lr-text-select` (`detail: { text, anchor, rects }`) — fired on selection end inside the rendered
 content. `lr-anchor-result` (`detail: { found }`) — fired after an `anchor` assignment or a
 `scrollToAnchor()` call.
 
 **CSS parts:** `base`, `body`, `content`, `spinner`, `error`, `highlight` (a painted `text-quote`
-highlight), `search-match` (a painted in-document search match), and `search-match-active` (the
-currently active search match, also carries `search-match`).
+highlight), `highlight-actions` (keyboard-accessible actions for resolved highlights),
+`highlight-action` (one native highlight activation button), `search-match` (a painted in-document
+search match), and `search-match-active` (the currently active search match, also carries
+`search-match`).
 
 **Themeable custom properties:** `--lr-docx-viewer-max-height` (default `none`) — maximum block size
 of `[part="body"]`; also settable via the `max-height` property, which writes this token inline.

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

@@ -6,7 +6,7 @@
 - **Class** `LyraDoughnutChart`, also available unregistered from `@aceshooting/lyra-ui/components/charts/chart/doughnut-chart.class.js`
 - **Family** `components/charts/` — see `llms/index.md` for its siblings
 - **Optional peers** `chart.js`, `chartjs-plugin-datalabels`, `chartjs-plugin-zoom` — see `llms/peers.md`
-- **Themeable via** 7 parts, 7 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 11 parts, 7 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Documented with** `lr-line-chart`, `lr-bar-chart`, `lr-pie-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`
 
@@ -33,16 +33,18 @@ of every entry in these lists.**
 (`show-data-table`), `chartArea` (readonly). `type` is the only member that differs: read-only,
 locked to this tag's value.
 
-**Methods:** `resetZoom()`, `refreshTheme()`.
+**Methods:** `appendData(label, values, maxPoints?)`, `exportData('csv' | 'png')`, `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`,
-`error` (`role="alert"` message rendered in place of `canvas` when the optional `chart.js` peer
-dependency fails to load — see `llms/components/lr-chart.md`).
+**CSS parts:** `base`, `plot`, `canvas`, `legend`, `legend-item`, `legend-swatch`,
+`reset-zoom-button`, `description`, `data-table`, `center`, `error` (`role="alert"` message
+rendered in place of `canvas` when the optional `chart.js` peer dependency fails to load — see
+`llms/components/lr-chart.md`).
 
 **Themeable custom properties:** `--lr-chart-height`, `--lr-chart-grid-color`,
 `--lr-chart-tick-color`, `--lr-chart-legend-color`, `--lr-chart-tooltip-bg`,
@@ -69,8 +71,8 @@ same set, so one rule retunes them together.
 - `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.
+- `lr-bubble-chart` consumes the exported `ChartPoint` shape directly. Set `x`/`y`, optional `r`
+  for bubble radius, and optional `label` for the point-level accessible/event/export label; no
+  runtime cast is needed.
 
 ---

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

@@ -131,7 +131,9 @@ called with no second argument, so `event.detail` is `null`, not `undefined`; fi
 when the parent `<lr-menu>`'s own Enter/Space keydown handling calls `select()` on the currently
 roving-focused item), `lr-menu-item-change` (`detail: { value, checked }` — fired when a
 `type="checkbox"` item is activated and its `checked` state toggled, in addition to — never instead
-of — `lr-menu-item-select`; never fired for `type="normal"`)
+of — `lr-menu-item-select`; never fired for `type="normal"`),
+`lr-menu-item-state-change` (`detail: { disabled, hidden }` — emitted when either navigability
+state changes so the parent menu can repair its roving-tabindex state immediately)
 
 **Slots:** default (the item's label content), `icon` (optional leading icon)