@aceshooting/lyra-ui 7.6.0 → 7.7.0

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

@@ -6,7 +6,7 @@
 - **Class** `LyraJsonViewer`, also available unregistered from `@aceshooting/lyra-ui/components/utility/json-viewer/json-viewer.class.js`
 - **Family** `components/utility/` — see `llms/index.md` for its siblings
 - **Optional peers** none
-- **Themeable via** 9 parts, 8 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 10 parts, 9 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`
 
 ---
@@ -26,7 +26,9 @@ stack overflow on cyclic `data`.
 - `collapsedDepth?: number` (attribute `collapsed-depth`) — nodes at or beyond this nesting depth
   (root = `0`) start collapsed; omitted/`undefined` means nothing auto-collapses
 - `maxHeight: string = ''` (attribute `max-height`) — a CSS length (e.g. `"20rem"`); once set, the
-  viewer scrolls internally past this height instead of growing the page
+  viewer scrolls internally past this height instead of growing the page. Values that do not parse
+  as CSS `max-height`, contain declaration breaks, or contain `url()` are ignored, leaving
+  `--lr-json-viewer-max-height` in control
 - `copyable: boolean = false` (reflected) — shows copy-to-clipboard affordances: one for the whole
   value, plus one per node
 - `search: string = ''` — case-insensitive substring match against keys/values; matches are
@@ -53,7 +55,8 @@ search query, match count, or active-match cursor changes, from `runSearch()`/`s
 
 **CSS parts:** `base` (root scroll container, respects `max-height`), `toolbar` (wrapper around the
 top-level copy button, only rendered when `copyable`), `tree` (wrapper around the rendered node
-tree), `key` (an object property key or array index label, `data-match` while it matches `search`,
+tree; a host `aria-label` is forwarded here), `row` (every structural opening/value and
+closing-delimiter row), `key` (an object property key or array index label, `data-match` while it matches `search`,
 `data-active` while it is the current `searchNext()`/`searchPrevious()` cursor position),
 `value` (a primitive value's text — carries `data-type` of
 `string`/`number`/`boolean`/`null`/`undefined`/`circular` for per-type coloring, `data-match`
@@ -71,6 +74,8 @@ until `max-height` is set), `--lr-json-viewer-font` (default `var(--lr-font-mono
 box-shadow, of a key/value that currently matches `search`. Component-scoped indirection over the
 shared `--lr-color-warning-quiet` token, so a consumer can retheme just this search-match highlight
 without repainting every other warning-toned surface that reads the same shared token;
+`--lr-json-viewer-row-hover-bg` (default `var(--lr-color-brand-quiet)`) — structural-row hover
+background;
 `--lr-json-viewer-active-outline` (default `var(--lr-focus-ring-color)`) — outline color for the
 current imperative search match; `--lr-json-viewer-string-color` (default
 `var(--lr-color-success)`), `--lr-json-viewer-number-color` (default `var(--lr-color-brand)`),
@@ -109,5 +114,7 @@ html`<lr-json-viewer .data=${apiResponse} copyable max-height="24rem" search=${q
   a different shape.
 - Per-node copy buttons call `stopPropagation()` on click so clicking one doesn't also toggle the
   row's expand/collapse state.
+- Whole-value copy always produces text, including for a root `undefined`, `Symbol`, or function
+  that native `JSON.stringify()` would otherwise return as no value.
 
 ---

package/llms/components/lr-kbd.md

@@ -44,8 +44,9 @@ resolves a full `keys` string with the same optional localization callback.
 **Slots:** default — an escape hatch for fully custom key-cap content (e.g. an icon instead of a
 text glyph). When it has any real (non-whitespace) content, it replaces the `keys`-driven rendering
 entirely and this component stops *computing* its own `aria-label` from `keys`, leaving the slotted
-content to carry its own accessible name — a host-supplied `aria-label` attribute is still forwarded
-onto the rendered chip in either mode, custom content included.
+content to carry its own accessible name. A host-supplied `aria-label` in custom mode is forwarded
+to `[part="base"]` together with `role="img"`; without one, the wrapper adds no image role and
+leaves the slotted content's own semantics exposed.
 
 **CSS parts:** `base` (the chip root), `key` (one per rendered token).
 

package/llms/components/lr-knowledge-base-admin.md

@@ -19,7 +19,9 @@ permissions, and connector settings go in the `settings` slot.
 
 **Properties:** `sources: KnowledgeSource[] = []` (attribute: false); `ingestionItems:
 IngestionQueueItem[] = []` (attribute: false); `activeTab: 'sources' | 'ingestion' = 'sources'`;
-`label: string = ''`; `hideIngestion: boolean = false`.
+`label: string = ''` (visible heading and accessible-name fallback; a host `aria-label` wins);
+`hideIngestion: boolean = false`. If ingestion is active when it becomes hidden, `activeTab`
+normalizes to `'sources'`, emits `lr-tab-change`, and moves focus to the Sources tab when needed.
 
 **Events:** `lr-tab-change` (`{ tab }`), `lr-source-create`, `lr-source-sync`, `lr-source-pause`,
 `lr-source-delete`, `lr-ingestion-retry`, and `lr-ingestion-cancel` (the latter four preserve the

package/llms/components/lr-knowledge-graph-explorer.md

@@ -35,7 +35,8 @@ overlay. Composes `lr-graph`, `lr-graph-legend`, `lr-entity-card`, `lr-neighbor-
 (self-managed but presettable/observable — this component toggles its own copy on interaction, the
 same self-toggle-then-emit contract `lr-graph-legend` uses, so every feature works with zero host wiring)
 - `hiddenTypes: string[] = []` (attribute: false) — forwarded to both `lr-graph.hiddenTypes` and
-  `lr-graph-legend.hiddenTypes`
+  `lr-graph-legend.hiddenTypes`; hidden nodes are also excluded from explorer search results,
+  neighbor rows, and activation
 - `selectedNodeId: string | null = null` (attribute `selected-node-id`) — drives the details popover
   and `lr-graph.selectedNodeIds`; `null` shows no selection and keeps the popover closed
 - `pinnedNodeIds: string[] = []` (attribute: false) — exactly two pinned nodes reveals the "Find

package/llms/components/lr-known-date.md

@@ -45,7 +45,8 @@ field currently has focus.
 
 **Events:** `input` (every keystroke), `change` (a field blur where the composite value newly
 transitioned), plus re-dispatched bubbling/composed `focus` and `blur` (`blur` fires once when focus
-leaves all three fields, not per field-to-field Tab). `input`/`change` detail is
+leaves all three fields, not per field-to-field Tab; each entry into the control likewise produces
+exactly one public `focus`, with the private trusted focus suppressed). `input`/`change` detail is
 `{ value, day, month, year, field }` — `value` is the canonical ISO date or `''`, `day`/`month`/`year`
 are the live raw typed text, and `field` is `'day' | 'month' | 'year'`, whichever was last edited.
 

package/llms/components/lr-lightbox.md

@@ -27,16 +27,17 @@ trap, Escape/backdrop dismissal, scroll lock, and focus return.
   event) when `images` shrinks.
 - `loop: boolean = false` (reflected) — wraps prev/next past the ends.
 - `noLightDismiss: boolean = false` (attribute `no-light-dismiss`) — opts out of backdrop dismissal.
-- `showCounter: boolean = true` (attribute `show-counter`) — shows `[part="counter"]` and its
-  live-region announcement.
+- `showCounter: boolean = true` (attribute `show-counter`) — shows the visible `[part="counter"]`.
+  The independent `[part="live-region"]` announcement remains active when the counter is hidden.
 - `minZoom: number = 0.5`, `maxZoom: number = 4`, `zoomStep: number = 0.25` (attributes `min-zoom`/
   `max-zoom`/`zoom-step`) — pure pass-throughs to the embedded `<lr-zoomable-frame>`, which does the
   normalizing.
 - `accessibleLabel: string | null = null` (attribute `aria-label`) — the panel's accessible name,
   overriding the localized `lightboxLabel`.
 
-**Methods:** `next()`, `previous()`, `goTo(index)`, `close(reason?)` — `reason` defaults to `'api'`
-and is forwarded as the close event's detail.
+**Methods:** `next()`, `previous()`, `goTo(index)`, `close(reason?)` — `goTo()` ignores a non-finite
+index without changing state or emitting `lr-index-change`; `reason` defaults to `'api'` and is
+forwarded as the close event's detail.
 
 **Events:** `lr-lightbox-close` (`detail: LyraLightboxCloseReason = 'escape' | 'backdrop' |
 'close-button' | 'api' | 'unmount' | (string & {})`; **cancelable** — `preventDefault()` blocks

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

@@ -6,7 +6,7 @@
 - **Class** `LyraLineChart`, also available unregistered from `@aceshooting/lyra-ui/components/charts/chart/line-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-bar-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`
 
@@ -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-lite-chart.md

@@ -24,9 +24,11 @@ passthrough). Not a subclass of `LyraChart`.
 - `type: LyraLiteChartType = 'bar'` — `'bar' | 'line'`
 - `labels: string[] = []` (attribute: false)
 - `datasets: LiteSeries[] = []` (attribute: false) — `LiteSeries { label: string; data:
-  (number|null)[]; color?: string }`
+  (number|null)[]; color?: string }`; `color` accepts a valid CSS `color`, while invalid values,
+  declaration-breaking input, and `url()` paint servers fall back to the built-in palette
 - `legend: boolean = false`
-- `height: string = '280px'`
+- `height: string = '280px'` — accepts a valid CSS `height`; invalid values, declaration-breaking
+  input, and `url()` leave the stylesheet's `--lr-chart-height` default/consumer override in control
 - `xLabel: string = ''` (attribute `x-label`)
 - `yLabel: string = ''` (attribute `y-label`)
 - `beginAtZero: boolean = true` (attribute `begin-at-zero`)
@@ -53,16 +55,19 @@ passthrough). Not a subclass of `LyraChart`.
 - `maxLabels?: number` (attribute `max-labels`, type Number) — decimates which category axis labels
   actually render *text* when `labels.length > maxLabels` (bars themselves are never decimated, only
   their axis `<text>` labels): always shows the first and last label, and roughly evenly distributes
-  the rest between them. Works in either `layout` mode. Unset (the default) renders every label,
-  unchanged.
+  the rest between them. Works in either `layout` mode. Unset (the default) renders every label.
+  Each rendered category label is allocation-aware: narrow/long text is ellipsized before paint,
+  with the complete caller label retained as its accessible name.
 - `barX?: (index: number) => number` (attribute: false, bar type only) — overrides the internal
   per-category x-origin formula (`plotX + i * slot`) used by both bars and their axis labels, so a
   consumer can pixel-align this chart's bars with a sibling `<lr-heatmap>` calendar's week columns
   (see that component's own `columnX`) by supplying the same coordinate function to both. Unset (the
   default) is the original formula, unchanged.
 - `pointText?: (label: string, value: number, datasetIndex: number) => string` (attribute: false) —
-  overrides the per-bar/per-point `<title>`/`aria-label` tooltip text (mirrors `lr-heatmap`'s
-  `cellText`). Falls back to the built-in raw-value template when unset.
+  overrides the per-bar/per-point native SVG `<title>` text (mirrors `lr-heatmap`'s `cellText`).
+  That one `<title>` supplies both the browser tooltip and the mark's accessible name; the component
+  does not duplicate the same string through `aria-label`. Falls back to the built-in raw-value
+  template when unset.
 - `legendText?: (label: string, datasetIndex: number) => string` (attribute: false) — appends
   formatter-supplied text (e.g. a value or percentage share) after each series' label in the
   built-in legend row, mirroring `pointText`/`tickFormat`'s opt-in-hook convention. Falls back to
@@ -83,14 +88,14 @@ passthrough). Not a subclass of `LyraChart`.
   ignores it entirely.
 - `hideAxis: boolean = false` (attribute `hide-axis`) — suppresses gridlines/y-axis tick labels
   altogether; x-axis category labels (rendered separately) are unaffected.
-- `selectedIndex: number[] = []` (attribute: false) — category indexes to mark `data-selected` on
-  every bar/segment at that index, across every dataset — e.g. to highlight a whole selected week's
-  column in a stacked chart. Empty (the default) reproduces the exact existing output: no bar
-  carries `data-selected`. This component takes no opinion on what the highlight looks like, only
-  which bars it applies to — style the highlight via the `--lr-lite-chart-selected-outline-color`
-  custom property (documented below). Note `::part(bar)[data-selected]` is **invalid CSS** — Shadow
-  Parts forbids an attribute selector after `::part()` — so it silently never matches; the outline
-  is painted inside the shadow root and exposed through that token instead.
+- `selectedIndex: number[] = []` (attribute: false) — applies to every interactive data mark for
+  both `type="bar"` and `type="line"`: matching bars and line points receive `data-selected` and
+  explicit `aria-pressed="true"`; all other marks render `aria-pressed="false"`. For a multi-series
+  chart, the category index selects the matching mark in every dataset. Empty is the default.
+  Style the built-in highlight through `--lr-lite-chart-selected-outline-color`. Note
+  `::part(bar)[data-selected]` and `::part(point)[data-selected]` are **invalid CSS** — Shadow Parts
+  forbids an attribute selector after `::part()` — so they silently never match; the outline is
+  painted inside the shadow root and exposed through that token instead.
 - `minBarHeight?: number` (attribute `min-bar-height`) — optional minimum visible bar height for
   small non-zero values
 - `accessibleLabel?: string` (attribute `accessible-label`) — SVG accessible-name override; a host
@@ -98,9 +103,11 @@ passthrough). Not a subclass of `LyraChart`.
 - `appendData(label, values, maxPoints?)` — appends one aligned category and optionally trims the
   oldest categories
 
-**Events:** `lr-point-click` — fired when a bar/point is activated (click, or Enter/Space while
-focused). `detail: { datasetIndex: number, index: number, label: string | undefined, value: number
-| null }` — same shape as `lr-chart`'s `lr-point-click`.
+**Events:** `lr-point-click` — fired for bars and line points on pointer activation or Enter/Space
+while focused. `detail: { datasetIndex: number, index: number, label: string | undefined, value:
+number | null }` — same shape as `lr-chart`'s `lr-point-click`. When different series' expanded
+line-point targets overlap, pointer activation selects the closest rendered point in two-dimensional
+screen space; an exact distance tie retains the point whose target received the click.
 
 **Methods:** `exportData('csv' | 'svg')` returns a spreadsheet-safe CSV snapshot or the current SVG
 markup. The method does not download a file; pair it with `lr-export-button` for download UX.
@@ -115,13 +122,13 @@ fresh, small SVG render is cheaper and more correct than a lossy cache.
 
 **Slots:** none.
 
-**CSS parts:** `base`, `grid-line`, `axis-label`, `axis-title`, `bar` (each bar rect; carries
-`data-selected` when its category index is in `selectedIndex`), `line`, `point`, `legend`,
-`legend-item`, `legend-swatch`, `legend-text` (extra per-item text after the series label,
-rendered only when `legendText` is set), `live-region` (the current mark announcement for keyboard
-users), `data-list` (a visually hidden list of all plotted data points — single-series only),
-`data-table` (a visually hidden category×series data table, rendered instead of `data-list` when
-there is more than one dataset).
+**CSS parts:** `base`, `grid-line`, `axis-label`, `axis-title`, `bar` and `point` (each carries
+`data-selected` when its category index is in `selectedIndex`, with explicit pressed state on every
+mark), `line`, `legend`, `legend-item`, `legend-swatch`, `legend-text` (extra per-item text after
+the series label, rendered only when `legendText` is set), `live-region` (the current mark
+announcement for keyboard users), `data-list` (a visually hidden list of all plotted data points —
+single-series only), `data-table` (a visually hidden category×series data table, rendered instead
+of `data-list` when there is more than one dataset).
 
 **Screen-reader data alternative:** a single dataset renders the flat `data-list` (one `<li>` per
 plotted point, matching the roving-tabindex mark order). More than one dataset instead renders a
@@ -138,10 +145,9 @@ blank instead of reporting a misleading zero.
 `--lr-chart-grid-color`, `--lr-chart-tick-color`, `--lr-chart-legend-color` — same token
 *names* as `lr-chart`, so a host already theming `lr-chart` themes this for free;
 `--lr-lite-chart-selected-outline-color` (default `var(--lr-color-brand)`) — the stroke drawn on
-`[part='bar'][data-selected]`, i.e. bars whose category index is in `selectedIndex` (bars only;
-`[part='point']` is never marked `data-selected`, and the stroke width is a fixed 2px). Unlike
-`lr-chart` (canvas-rendered, needs `getComputedStyle`-based re-theming on every draw), this is
-plain SVG/DOM and reads these via native CSS `var()` — no JS-side resolution step, and no
+selected `[part='bar']` and `[part='point']` marks whose category index is in `selectedIndex`.
+Unlike `lr-chart` (canvas-rendered, needs `getComputedStyle`-based re-theming on every draw), this
+is plain SVG/DOM and reads these via native CSS `var()` — no JS-side resolution step, and no
 `refreshTheme()` method needed (there's nothing to go stale).
 
 **Optional peer deps:** none. This is the point of the component.
@@ -163,10 +169,18 @@ plain SVG/DOM and reads these via native CSS `var()` — no JS-side resolution s
   always vertical.
 - No dual y-axis (`Series.axis: 'y2'`) — every series shares one y-axis/domain.
 - Series colors default to a fixed built-in 8-color categorical palette (round-robin by dataset
-  index) when `color` is unset — not configurable beyond passing `color` per series.
-- Bar/point elements are real focusable DOM nodes (`tabindex="0" role="button"`, each with its own
-  `aria-label`), so the `<svg>` itself uses `role="group"`, not `role="img"` — an "img" role would
-  conflict with genuinely interactive descendants (axe's `nested-interactive` rule).
+  index) when `color` is unset or invalid — not configurable beyond passing a valid CSS `color`
+  per series.
+- Bar/point elements are real focusable DOM nodes (`role="button"` with one roving `tabindex="0"`);
+  each native SVG `<title>` is the mark's sole accessible name and tooltip. The `<svg>` itself uses
+  `role="group"`, not `role="img"` — an image role would conflict with genuinely interactive
+  descendants (axe's `nested-interactive` rule).
+- Dense transparent hit regions expand toward 24px only while remaining inside the neighboring
+  mark's midpoint lane; stacked segments keep their own vertical region. This prevents a
+  later-painted mark from stealing pointer input from an adjacent datum. Cross-series line targets
+  are additionally arbitrated by two-dimensional screen distance.
+- In narrow allocations, category labels are ellipsized to their available lane and retain the
+  complete label through `aria-label`; SVG overflow is contained within the host.
 - Tick values use a standard "nice numbers" (1/2/5 × 10ⁿ) rounding step, not exact data min/max —
   intentional (readable axis labels), matches how most charting libraries pick tick steps.
 

package/llms/components/lr-map.md

@@ -42,7 +42,9 @@ and additive plain-GeoJSON `dataLayers`, plus a raw `map` escape hatch for anyth
   content, sanitize anything derived from user input first; prefer `label` (`Popup.setText()`,
   escaped) when the content is plain text. A marker whose `color` changes for a persisting `id`
   can't be recolored in place (no `Marker.setColor()`) and is torn down/reconstructed instead — see
-  gotchas.
+  gotchas. Entries with non-finite coordinates or latitude outside `[-90, 90]` are skipped without
+  aborting valid siblings. `color` is used only when the browser accepts it as CSS `color`;
+  declaration breaks and `url()` paint servers fall back to MapLibre's default marker color.
 - `dataLayers: GeoJsonDataLayer[] = []` (attribute: false) — `GeoJsonDataLayer { sourceId: string;
   geojson: GeoJSON.Feature | GeoJSON.FeatureCollection; tone?: 'accent' | 'success' | 'warning' |
   'danger' | 'neutral' }`. Each entry adds one GeoJSON source plus three layers
@@ -54,10 +56,9 @@ and additive plain-GeoJSON `dataLayers`, plus a raw `map` escape hatch for anyth
   is: an entry whose `sourceId` persists across a `dataLayers` reassignment gets its GeoJSON updated
   in place (`setData()`), one that's dropped has its source/layers removed, and a genuinely new
   `sourceId` gets a new source/layers — nothing leaks on removal, style change, or disconnect.
-- `label: string = ''` — accessible name for the map region, applied as `[part="base"]`'s
-  `aria-label`. A plain `aria-label` attribute on the host itself is honored as a fallback when
-  `label` is left unset, matching `lr-slider`/`lr-checkbox`/`lr-switch`; with neither set, it
-  falls back to the localized `'map'` message.
+- `label: string = ''` — accessible-name fallback for MapLibre's actual focusable canvas. A plain
+  host `aria-label` takes precedence over `label`; with neither set, the canvas uses the localized
+  `'map'` message. The non-semantic `[part="base"]` wrapper is not named instead.
 
 **Getters:** `map` → the raw `maplibregl.Map` instance.
 
@@ -116,6 +117,10 @@ https://maplibre.org/maplibre-gl-js/docs/#esm.
   layer/source maplibre-gl knows about.
 - Point markers now have a declarative API (`markers`, above) with popup support — the `.map` escape
   hatch and manual `new maplibregl.Marker()` are no longer the only way to place pins.
+- A marker uses `label` as its accessible name, falling back to the localized map label. Popup
+  ownership is exposed through `aria-controls`/`aria-expanded`; an open popup is a named
+  `role="dialog"` and its close button is localized. The map canvas, markers, popups, and MapLibre's
+  own control strings all follow the component's effective locale.
 - a marker whose `color` changes for a persisting `id` is torn down and reconstructed (maplibre-gl's
   `Marker` has no `setColor()`) rather than mutated in place — this also closes any popup the user
   currently has open on that marker (a fresh, closed `Popup` is built for the new instance); an

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

@@ -42,6 +42,12 @@ request. Both are no-ops before a frame exists.
 (`{ level, value }`), and `lr-mcp-resize` (`{ height }`). These are host-authorized requests; the
 component does not execute tools, send messages, or navigate itself.
 
+Changing `resource` mounts a fresh iframe/window generation; messages from the prior
+`contentWindow` are ignored even when two opaque-origin inline documents otherwise look alike.
+Changing only `height`/`maxHeight` updates frame geometry without returning an already-ready frame
+to its loading state. The initial host context reports `effectiveLocale`, so inherited/document
+locale and per-element locale overrides follow the same precedence as the rest of Lyra UI.
+
 **CSS parts:** `base`, `frame`, `loading`, `error`.
 
 **Slots:** none. **Optional peer deps:** none.

package/llms/components/lr-media-card.md

@@ -34,7 +34,9 @@ final.
 - `maxHeight: string = ''` (attribute `max-height`) — a CSS length (e.g. `"16rem"`); once set,
   overrides the `--lr-media-card-max-height` custom property for this instance only (applied
   inline on `[part="base"]`, so it reliably wins over a `:host{}`-declared default from outside the
-  shadow root) — same contract as `<lr-document-preview>`'s identically-named prop.
+  shadow root) — same contract as `<lr-document-preview>`'s identically-named prop. Values that do
+  not parse as CSS `max-height`, contain declaration breaks, or contain `url()` are ignored, leaving
+  the stylesheet token in control.
 - `appearance: 'card' | 'plain' = 'card'` (reflected) — visual chrome, mirroring
   `<lr-source-card>`'s `appearance` vocabulary. `'card'` (the default) keeps the bordered, filled
   box. `'plain'` removes `[part="base"]`'s border, background, padding, and corner radius, so a

package/llms/components/lr-mention-popover.md

@@ -156,8 +156,11 @@ fresh `query` is the proxy for "the caret may have moved").
 - A caret that moves for a reason other than typing (e.g. a mouse click elsewhere in the text while
   the popover happens to still be open) is not separately tracked — force a re-measure by toggling
   `open` or reassigning `anchor`.
-- `activeIndex` resets to `0` whenever `query` or `items` changes, but not when only `anchor`
-  changes — reassigning `anchor` alone preserves whatever row was last highlighted.
+- `activeIndex` resets to `0` whenever `query`, `items`, or `filter` changes, but not when only
+  `anchor` changes — reassigning `anchor` alone preserves whatever row was last highlighted. If
+  fallback focus currently lives in the listbox and filtering removes every option, closing,
+  emptying, or disconnecting the popover returns focus to the connected anchor before removing the
+  active option.
 - There's no persisted "selection" the way `<lr-combobox>`'s own listbox has one — a mention is
   either committed (closing the popover) or dismissed with nothing chosen. `aria-selected="true"`
   here marks whichever row is currently *active* (what Enter/Tab would commit right now, per the

package/llms/components/lr-menu-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)
 

package/llms/components/lr-menu.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)
 

package/llms/components/lr-message-feedback.md

@@ -30,7 +30,8 @@ rating opens the detail panel, and `disabled: boolean = false` (reflected) for a
 **Events:** `lr-change` — `detail: { value: 'up' | 'down' | null }`, fired when a thumb's rating
 changes or clears. `lr-submit` — `detail: { value: 'up' | 'down'; reasonIds: string[]; comment:
 string }`, fired by the panel's submit button (`value` is never `null` here — the panel only exists
-for a set rating).
+for a set rating). The optional comment `<textarea>`'s native `focus` and `blur` are re-dispatched
+as bubbling, composed host events.
 
 **CSS parts:** `base` (the root), `thumbs` (wrapper around both thumb buttons), `up-button`,
 `down-button`, `panel` (the inline detail disclosure, only rendered when `reasons` is non-empty or

package/llms/components/lr-message-parts.md

@@ -26,7 +26,11 @@ part to the built-in renderer; `label: string = ''`; `accessibleLabel: string |
 `MessagePartRenderer = (part: MessagePart, index: number) => unknown`; `MessagePart` and its
 discriminated part shapes come from the `@aceshooting/lyra-ui/ai` subpath.
 
-**Events:** `lr-citation-select` (`{ citation }`), `lr-part-retry` (`{ part }`).
+**Events:** `lr-citation-select` (`{ citation }`), `lr-part-retry` (`{ part }`). Composed child
+events pass through unchanged: `lr-anchor-result`, `lr-citation-open`, `lr-copy`,
+`lr-highlight-activate`, `lr-link-click`, `lr-preview`, `lr-remove`, `lr-render-error`, `lr-retry`,
+`lr-search-change`, `lr-text-select`, `lr-toggle`, `lr-tool-call-chip-select`,
+`lr-tool-chip-select`, `lr-widget-action`, and `lr-widget-state-change`.
 
 **CSS parts:** `base`, `part`, `part-streaming`, `text`, `reasoning`, `tool-call`, `tool-result`,
 `citation`, `attachment`, `data`, `audio`, `audio-transcript`, `error`, `retry`.

package/llms/components/lr-model-select.md

@@ -88,7 +88,9 @@ combination (`catalog` empty/unset, or `allowCustom` true) renders the free-text
 (`[part="combobox"]`/`[part="combobox-input"]`) with live substring filtering against the catalog (id or
 label, case-insensitive). The mode is re-evaluated on every render, so toggling `allowCustom` or clearing
 `catalog` at runtime switches modes live, repositioning the shared `[part="listbox"]` popover against
-whichever element is the active anchor.
+whichever element is the active anchor. Replacing `catalog` while free-text mode remains open
+refilters suggestions without erasing the user's current draft; controlled `value` changes and
+actual mode switches still rebase the input to the committed value.
 
 A `value` that isn't present in `catalog` (e.g. a model id saved from a provider whose live catalog has
 since changed) is never silently dropped: it's appended to the rendered option list as a synthetic,
@@ -103,6 +105,8 @@ visually-distinct row (dashed border, italic label, "not in catalog" badge) comp
 - `change` (`Event`, no detail) — fired alongside `lr-change`, mirroring `<lr-select>`/
   `<lr-combobox>`'s native-style value-change pair so native form bindings/framework `v-model`
   handlers behave consistently across the picker family.
+- `input` (`Event`, no detail) — fired immediately before `change` alongside each committed
+  `lr-change`, providing the same native-style value-event pair as `<lr-select>`/`<lr-combobox>`.
 - `blur` (no detail) — re-dispatched from the free-text mode's internal `<input>`'s own `blur`,
   bubbling and composed unlike the native event. Closed-dropdown mode's trigger `<button>` has no
   equivalent re-dispatch, matching `<lr-select>`'s own trigger.

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

@@ -33,9 +33,10 @@ JSON text; wins over `src` and is parsed (and validated) synchronously. `name: s
 accessible label, and matched against a `fragment` anchor's cell id. `outputCollapseLines: number =
 40` (attribute `output-collapse-lines`) — a plain-text output longer than this many lines renders
 collapsed behind a toggle; `0` disables collapsing. `maxHeight: string = ''` (attribute
-`max-height`) — once set, the notebook scrolls internally past this height. `anchorKinds` is a
-readonly `['node-path', 'fragment']` (this viewer's supported `LyraAnchor.kind` values for the
-shared anchor-target contract).
+`max-height`) — once set, the notebook scrolls internally past this height; invalid CSS
+`max-height` values, declaration breaks, and `url()` are ignored. `anchorKinds` is a readonly
+`['node-path', 'fragment']` (this viewer's supported `LyraAnchor.kind` values for the shared
+anchor-target contract).
 
 **Methods:** `search(query)` resolves the match count over cell sources and text outputs — a
 matching cell counts as one match (empty/whitespace query behaves like `clearSearch()`);
@@ -86,3 +87,6 @@ the element or on any ancestor.
 
 A notebook major version outside 4.0–4.5, an invalid shape, or more than 2,000 cells renders a
 localized error and fires `lr-render-error` instead of the notebook.
+
+PNG/JPEG outputs use their `text/plain` representation as alt text, falling back to a localized
+code-cell name. Sanitized SVG output is wrapped in a named `role="img"` with the same fallback.

package/llms/components/lr-option.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-page-rail.md

@@ -29,6 +29,11 @@ truth.
 **Events:** `lr-page-select` — a page row was activated (click, or Enter/Space on a focused row).
 `detail: { page }`. In wired mode the rail also sets `viewer.page` itself.
 
+If `pageCount` shrinks past the currently focused row, focus moves to the absolute last remaining
+page instead of using the rendered window's local index or being lost with the virtualized row.
+Rapid consecutive shrinks supersede an in-flight repair, so focus lands on the latest count. The
+numeric type-ahead buffer is cleared on detach.
+
 **CSS parts:** `base` (the rail), `pages` (the embedded `<lr-virtual-list>`), `page` (one page
 button), `page-current` (the button for the current `page`), `thumbnail` (the thumbnail canvas
 wrapper), `page-number` (the visible page number), `heat` (the heat-marker cluster), `heat-dot` (one

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

@@ -28,9 +28,12 @@ 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`. `maxHeight: string = ''` (attribute `max-height`) is a
 CSS length that, once set, overrides `--lr-pdf-viewer-height` — the block size of the virtualized
-page list — declaratively, writing it inline on `[part="base"]`. `anchorKinds` is a readonly
+ page list — declaratively, writing it inline on `[part="base"]`; invalid CSS `max-height` values,
+ declaration breaks, and `url()` are ignored. `anchorKinds` is a readonly
 `['page', 'text-quote', 'region']` (this viewer's supported `LyraAnchor.kind` values for the shared
-anchor-target contract).
+anchor-target contract). Page and page-addressed region anchors require an in-range integer page
+and are rejected rather than clamped; region rectangles also require finite coordinates and
+nonnegative dimensions.
 
 **Events:**
 - `lr-render-error` — `detail: { error }` — fetching, parsing, or rendering (page canvas or text
@@ -57,7 +60,8 @@ of one page (per-page LRU-cached, 64 pages), rejecting on no loaded document or
 `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.
+table of contents as `PdfOutlineItem[]` (`{ title, page?, children? }`), `[]` when there is none;
+peer output is capped at 10,000 unique items and 100 levels, with cycles ignored.
 `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.
@@ -96,3 +100,6 @@ rendering without it.
 
 Remote resources are capped at 25 MB; exceeding it surfaces the localized
 `documentPreviewResourceTooLarge` message instead of the PDF.
+
+Anchor navigation is generation-guarded: a newer anchor, document replacement, or disconnect
+prevents stale page/text/region work from scrolling or reporting success.

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

@@ -6,7 +6,7 @@
 - **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-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-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`
 
@@ -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.
 
 ---