@aceshooting/lyra-ui 13.0.1 → 14.1.0

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

@@ -24,6 +24,10 @@ and animated panel. The two components intentionally keep distinct vocabularies:
 use `expanded`, `label`, and `expand()`/`collapse()`/`toggle()`, while `open`, `summary`, and
 `show()`/`hide()` belong only to Details.
 
+`lr-toggle` reports the direction and source of an accepted Details transition. Accordion
+coordinates only its direct `lr-accordion-item` children; Details retains independent state and
+optional grouping through a shared non-empty `name`.
+
 **Breaking in 9.0.0:** an accordion coordinates direct `lr-accordion-item` children only. Direct
 `lr-details` panels used to be accepted as well; they are not any more. A `lr-details` slotted into
 an accordion today is ordinary content owning its own disclosure lifecycle — the group applies
@@ -141,16 +145,17 @@ from assistive technology: do not place independent links, buttons, inputs, form
 targets there. The accordion-item `icon` slot follows the same flattened-tree inert and aria-hidden
 visual contract, while the trigger button remains the sole action. Details has `summary`,
 `header-actions`, `expand-icon`, `collapse-icon`, plus default content. `header-actions` renders
-extra controls (e.g. a trailing "add" button) inside the `<summary>` header row — the one subtree a
-native `<details>` keeps out of its generated content box — so they stay rendered, visible, and
-hit-testable while the panel is collapsed. Activating one never toggles the panel: a click whose
+extra controls (e.g. a trailing "add" button) as a sibling of the private native `<details>` in the
+complete header row, so they stay rendered, visible, and hit-testable while the panel is collapsed
+or disabled. Activating one never toggles the panel: a click whose
 composed path crosses `[part~="header-actions"]` is exempted from disclosure activation. Its wrapper
 is hidden and reclaims layout space whenever the slot is empty.
 
 **CSS parts:** accordion exposes `base`. Accordion item exposes `base` and `accordion-item` on the
 same outer wrapper, plus `heading`, `button`, `label`, `icon`, `panel`, and `content`. Details
-exposes `base` and `details` on the same native `<details>` wrapper, plus `header`, `summary`,
-`icon`, `header-actions`, and `content`.
+exposes `base` and `details` on the same outer container, plus `header`, `summary`, `icon`,
+`header-actions`, and `content`. The native `<details>` is private; `content` is inside its
+findable `hidden="until-found"` closed-state gate.
 The Details icon wrapper also carries Shoelace's `summary-icon` alias, so either part name styles
 the same node. `header-actions` is the wrapper around the `header-actions` slot.
 

package/llms/components/lr-accordion.md

@@ -24,6 +24,10 @@ and animated panel. The two components intentionally keep distinct vocabularies:
 use `expanded`, `label`, and `expand()`/`collapse()`/`toggle()`, while `open`, `summary`, and
 `show()`/`hide()` belong only to Details.
 
+`lr-toggle` reports the direction and source of an accepted Details transition. Accordion
+coordinates only its direct `lr-accordion-item` children; Details retains independent state and
+optional grouping through a shared non-empty `name`.
+
 **Breaking in 9.0.0:** an accordion coordinates direct `lr-accordion-item` children only. Direct
 `lr-details` panels used to be accepted as well; they are not any more. A `lr-details` slotted into
 an accordion today is ordinary content owning its own disclosure lifecycle — the group applies
@@ -141,16 +145,17 @@ from assistive technology: do not place independent links, buttons, inputs, form
 targets there. The accordion-item `icon` slot follows the same flattened-tree inert and aria-hidden
 visual contract, while the trigger button remains the sole action. Details has `summary`,
 `header-actions`, `expand-icon`, `collapse-icon`, plus default content. `header-actions` renders
-extra controls (e.g. a trailing "add" button) inside the `<summary>` header row — the one subtree a
-native `<details>` keeps out of its generated content box — so they stay rendered, visible, and
-hit-testable while the panel is collapsed. Activating one never toggles the panel: a click whose
+extra controls (e.g. a trailing "add" button) as a sibling of the private native `<details>` in the
+complete header row, so they stay rendered, visible, and hit-testable while the panel is collapsed
+or disabled. Activating one never toggles the panel: a click whose
 composed path crosses `[part~="header-actions"]` is exempted from disclosure activation. Its wrapper
 is hidden and reclaims layout space whenever the slot is empty.
 
 **CSS parts:** accordion exposes `base`. Accordion item exposes `base` and `accordion-item` on the
 same outer wrapper, plus `heading`, `button`, `label`, `icon`, `panel`, and `content`. Details
-exposes `base` and `details` on the same native `<details>` wrapper, plus `header`, `summary`,
-`icon`, `header-actions`, and `content`.
+exposes `base` and `details` on the same outer container, plus `header`, `summary`, `icon`,
+`header-actions`, and `content`. The native `<details>` is private; `content` is inside its
+findable `hidden="until-found"` closed-state gate.
 The Details icon wrapper also carries Shoelace's `summary-icon` alias, so either part name styles
 the same node. `header-actions` is the wrapper around the `header-actions` slot.
 

package/llms/components/lr-activity-feed.md

@@ -16,8 +16,8 @@
 
 ## `lr-activity-feed`
 
-An append-only streaming log of granular agent actions ("Searching the web…", "Read
-src/index.ts"), collapsing to a localized "Completed N steps" summary once the run is over. Entries
+An append-only streaming log of granular agent actions ("Searching the web…", "Read the
+application entry point"), collapsing to a localized "Completed N steps" summary once the run is over. Entries
 never change state once added — a step whose status mutates in place belongs to `<lr-task-list>`
 instead. Implements the shared follow (stick-to-bottom) contract. At/above `virtualizeAt`
 entries, the body renders through an internal `<lr-virtual-list>` instead of a plain keyed list.
@@ -34,13 +34,14 @@ unset. `mode: 'live' | 'post-hoc' =
 `label?: string` — omission localizes `activityFeedLabel` (`'Activity'` in the built-in English
 catalog), while any supplied string is a verbatim override, including `'Activity'` under a
 non-English `.strings` catalog and `''`. A present host `aria-label` names the owned list in both
-plain and virtualized rendering paths while `label` remains the visible header text —
+plain and virtualized rendering paths while `label` remains the visible header text. Host
+`aria-labelledby` and `aria-describedby` likewise reach that semantic list in both rendering paths —
 `showTimestamps: boolean = false` (attribute `show-timestamps`),
 `formatTimestamp?: (date: Date) => string` (attribute: false), `renderText?: (entry: ActivityEntry)
 => TemplateResult` (attribute: false) — overrides the default plain-text `entry-text` rendering with
 arbitrary rich content (e.g. rendered markdown, or markdown plus a trailing tool-call chip list),
-identically whether or not the feed is currently virtualized; fully replaces `[part="entry-text"]`
-rather than augmenting it, and `virtualizeAt: number = 199` (attribute
+identically whether or not the feed is currently virtualized; replaces the plain text **inside**
+the persistent `[part="entry-text"]` wrapper rather than removing that part, and `virtualizeAt: number = 199` (attribute
 `virtualize-at`).
 
 **Events:** `lr-toggle` (`detail: { expanded }`, the header was activated) and

package/llms/components/lr-agent-run.md

@@ -31,7 +31,7 @@ cancelable. Retry is available for `error` and `cancelled`.
 **Properties:**
 
 - `run: AgentRun | null = null` (attribute: false) — **`AgentRun`, imported from
-  `@aceshooting/lyra-ui/ai`** (`src/ai/types.ts`): `{ id: string; status: AgentStatus; startedAt?:
+  `@aceshooting/lyra-ui/ai`**: `{ id: string; status: AgentStatus; startedAt?:
 number; endedAt?: number; model?: string; costEstimate?: number; steps: readonly AgentStep[] }`, where
   `AgentStatus { kind: AgentStatusKind; message?: string }` and `AgentStep { id: string; kind:
 string; label: string; status: AgentStatus; startedAt?: number; endedAt?: number }`. All timestamps

package/llms/components/lr-agent-trace.md

@@ -19,6 +19,9 @@
 Provider-neutral agent/LLM trace view combining span-kind filters, handoff quick-jumps, and a
 hierarchical trace tree from one shared `spans` array.
 
+Span views omit whitespace-only IDs and preserve every nonblank business ID exactly, including
+surrounding whitespace. The first valid admitted duplicate continues to win.
+
 **Properties:**
 
 - `spans: LyraSpan[] = []` (attribute: false) — the full, unfiltered array; identical contract to

package/llms/components/lr-agent-workspace.md

@@ -23,7 +23,7 @@ grounding, and context state: transcript + composer in the main pane, and a deta
 assign new data to the properties as the host receives updates.
 
 This is the single component that binds the most of the provider-neutral vocabulary exported from
-`@aceshooting/lyra-ui/ai` (`src/ai/types.ts`) at once; a host that already holds `ChatMessage[]`,
+`@aceshooting/lyra-ui/ai` at once; a host that already holds `ChatMessage[]`,
 `AgentRun`, `RetrievalChunk[]`, `Citation[]`, and `GroundingAssessment` can wire this up with no
 adapters.
 
@@ -81,7 +81,8 @@ Citation; truncated?: boolean; omittedTokens?: number; redactions?: ContextInspe
   the border and padding; a supplied `composer` slot keeps its own frame.
 - `composerValue: string = ''` (attribute `composer-value`) — controlled composer value
 - `composerStatus: ChatComposerStatus = 'idle'` (attribute `composer-status`) — `'idle' | 'sending' |
-'streaming'`, `lr-chat-composer`'s own union
+'streaming'`, `lr-chat-composer`'s own union; invalid values read as `idle` without rewriting the
+  host attribute
 - `composerPlaceholder: string = ''` (attribute `composer-placeholder`)
 - `composerMinRows: number = 1` (attribute `composer-min-rows`), `composerMaxRows: number = 8`
   (attribute `composer-max-rows`)

package/llms/components/lr-animation.md

@@ -18,6 +18,10 @@
 
 Declaratively animates one slotted element through the native Web Animations API.
 
+An initial playing mount creates one native animation and emits one `lr-start`. A real target or
+timing change still rebuilds the animation, while replay and reconnect retain their normal
+start/finish lifecycle, including reduced motion.
+
 **Properties:**
 
 - `name: string = 'none'` — accepts any animation registry name. The built-in names are `'none' |

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

@@ -122,8 +122,10 @@ vetoing that one would leave `open` stuck `true` in a mode where it's meaningles
 `preventDefault()` to keep the overlay as it is for the other triggers),
 `lr-rail-resize-request` (`detail: LyraAppRailResizeDetail` = `{ widthPx: number }`; a cancelable
 proposed width from drag or keyboard stepping, emitted before the component assigns
-`railWidthPx` — call `preventDefault()` to keep the current width. It is not fired when a consumer
-sets `railWidthPx` directly), and `lr-rail-resize` (`detail: LyraAppRailResizeDetail` =
+`railWidthPx` — call `preventDefault()` to keep the current width. A synchronous request listener
+that disables resizing, leaves full mode, or disconnects the rail also cancels the proposal,
+preserving any width the listener assigned and publishing no accepted resize. Assigning only
+`railWidthPx` does not veto the proposal. It is not fired when a consumer sets `railWidthPx` directly), and `lr-rail-resize` (`detail: LyraAppRailResizeDetail` =
 `{ widthPx: number }`; non-cancelable committed width, emitted immediately for a genuine keyboard
 step and once at pointerup for a genuine drag. Clamped/no-op steps, canceled/lost gestures, and
 consumer property writes emit no committed event).

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

@@ -121,8 +121,10 @@ vetoing that one would leave `open` stuck `true` in a mode where it's meaningles
 `preventDefault()` to keep the overlay as it is for the other triggers),
 `lr-rail-resize-request` (`detail: LyraAppRailResizeDetail` = `{ widthPx: number }`; a cancelable
 proposed width from drag or keyboard stepping, emitted before the component assigns
-`railWidthPx` — call `preventDefault()` to keep the current width. It is not fired when a consumer
-sets `railWidthPx` directly), and `lr-rail-resize` (`detail: LyraAppRailResizeDetail` =
+`railWidthPx` — call `preventDefault()` to keep the current width. A synchronous request listener
+that disables resizing, leaves full mode, or disconnects the rail also cancels the proposal,
+preserving any width the listener assigned and publishing no accepted resize. Assigning only
+`railWidthPx` does not veto the proposal. It is not fired when a consumer sets `railWidthPx` directly), and `lr-rail-resize` (`detail: LyraAppRailResizeDetail` =
 `{ widthPx: number }`; non-cancelable committed width, emitted immediately for a genuine keyboard
 step and once at pointerup for a genuine drag. Clamped/no-op steps, canceled/lost gestures, and
 consumer property writes emit no committed event).

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

@@ -26,6 +26,12 @@ wins when both are present. When a real `File` or `preview-src` is available, th
 localized action that emits a plain, non-cancelable `lr-preview-request`; it never registers or owns a viewer
 or overlay, so the host composes the desired preview surface.
 
+An error already present at first mount or reconnection renders as existing state without an
+announcement, including a failure assigned while detached and reconnected before the next render. A
+new connected transition to error still appends one localized failure announcement; repeated
+connected failures remain separately announced, including a retry whose uploading and error writes
+coalesce into one update.
+
 **Properties:**
 
 - `file?: File` (attribute `false`, i.e. property-only) — when set, `name`/`bytes`/`mimeType`/the
@@ -115,9 +121,8 @@ already focused on the chip still hears an upload failure — goes to the librar
   can read at their own pace, and a retry that fails the same way twice is announced twice rather
   than being a silent no-op. The ticking `uploading` readout announces nothing at all — a live
   region re-announcing every progress tick is noise, not information.
-- A test that asserted `::part(status-text)` had `role="alert"` now fails; query
-  `[data-lr-live-region="assertive"]` in the document instead. `::part(status-text)` is still the
-  styling hook, and still the place to read the visible status wording.
+- Read the announcement from `[data-lr-live-region="assertive"]` in the document;
+  `::part(status-text)` remains the styling hook and visible-status text.
 
 **Themeable custom properties:** `--lr-attachment-chip-accent` (default
 `var(--lr-color-text-quiet)`), `--lr-attachment-chip-bg` (default `var(--lr-color-surface)`),

package/llms/components/lr-audio-visualizer.md

@@ -28,10 +28,11 @@ wired to a WebAudio `AnalyserNode`; `level: number | null = null` — a pre-comp
 hosts that already have one (e.g. `lr-push-to-talk`'s `lr-level` detail); `state: 'idle' |
 'listening' | 'thinking' | 'speaking' = 'idle'` (reflected) — drives the signal-less ambient
 animation and per-state coloring; `mode: AudioVisualizerMode = 'bars'` (`'bars' | 'waveform'`,
-reflected); `barCount: number = 5` (attribute `bar-count`); `gain: number = 1` — multiplier applied
-to the resolved amplitude; `label: string =
-''` — accessible-name override. Invalid `state` or `mode` attribute/property writes normalize to
-`idle` and `bars` respectively.
+reflected); `barCount: number = 5` (attribute `bar-count`, normalized to an integer in `[1, 64]`);
+`gain: number = 1` — multiplier applied to the resolved amplitude, with a non-finite value treated
+as `1`; `label: string = ''` — accessible-name override. `level` is clamped to `[0, 1]`; after gain,
+waveform and bar values are clamped to `[-1, 1]` and `[0, 1]` respectively. Invalid `state` or
+`mode` attribute/property writes normalize to `idle` and `bars` respectively.
 
 **Methods:** `refreshTheme()` re-reads themeable custom properties after a runtime theme change (the
 canvas resolves token values at paint time and cannot inherit `var()` directly). Canvas-bound
@@ -44,8 +45,10 @@ or empty `MediaStream` tears down the prior analyser transaction immediately and
 
 **Slots:** none.
 
-**CSS parts:** `base` (the root wrapper) and `canvas` (the drawing surface, `aria-hidden`; the host
-itself carries `role="img"` and the accessible name).
+**CSS parts:** `base` (the root wrapper) and `canvas` (the drawing surface, `aria-hidden`). The host
+supplies `role="img"` only while an author has not supplied a role; an authored role is preserved,
+and removing it restores `img`. If observation cannot be established, it draws eagerly; otherwise
+it waits for a valid observer entry and pauses offscreen.
 
 **Themeable custom properties:** `--lr-audio-visualizer-color` (default `var(--lr-color-brand)` —
 active bar/waveform color), `--lr-audio-visualizer-quiet-color` (default

package/llms/components/lr-av-player.md

@@ -25,6 +25,20 @@ distinct from `<lr-transcript-feed>` (live captions for an in-progress voice ses
 `anchorKinds: ['time-range']` only — no text selection is bound. The transcript virtualizes through
 `<lr-virtual-list>` the same way `lr-pdf-viewer` virtualizes pages.
 
+Removing `mime-type` consumes the absent hint safely and restores automatic video fallback unless
+`kind` explicitly selects audio. Attribute removal keeps its `null` property readback; an explicit
+empty hint remains empty, and a later audio MIME value restores audio detection.
+
+A cue with no `end` extends to the next strictly chronological applicable start, or remains
+open-ended when none exists. Equal starts do not end each other. The player indexes starts on cue
+assignment in at most O(n log n) work and reconciles each seek/time update in O(n) work. Caller
+order, first ID admission, explicit ends and overlap arbitration are retained; a paused seek uses
+replacement cues immediately, even before rendering. Duration changes preserve the same
+effective-start rules.
+
+An unavailable timeline keeps its resting border and background under hover and press. Enabled
+seeking retains token-driven pointer feedback.
+
 The default document-viewer renderer advertises `time-range` anchors but not search: the generic
 document payload has no cue/transcript field, so advertising search there would expose a control
 whose result is always empty. Standalone `<lr-av-player>` search remains available whenever the

package/llms/components/lr-avatar.md

@@ -22,6 +22,10 @@ named `icon` slot, label and image-load error event) and adds this library's sha
 `variant` vocabulary. Purely presentational, with no built-in interactivity; wrap it in a
 `<button>`/`<lr-menu>` trigger for a user-menu affordance.
 
+Removing the attribute consumes the label as absent while preserving its `null` property readback.
+Explicit empty labels remain empty, host `aria-label` precedence remains intact, and later label
+values restore the image or fallback name.
+
 **Properties:**
 
 - `initials: string = ''` — fallback text (typically 1-2 characters), shown whenever no glyph and no

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

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [llms-full.txt](../../llms-full.txt)
 - **Deprecations** none
 - **Optional peers** `chart.js`, `chartjs-plugin-annotation`, `chartjs-plugin-datalabels`, `chartjs-plugin-zoom` — see `llms/peers.md`
-- **Themeable via** 16 parts, 35 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 16 parts, 36 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Documented with** `lr-line-chart`, `lr-pie-chart`, `lr-doughnut-chart`, `lr-radar-chart`, `lr-polar-area-chart`, `lr-bubble-chart`, `lr-scatter-chart` (same section below)
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
@@ -58,7 +58,7 @@ failure transition is announced through the shared document-level light-DOM asse
 `--lr-chart-data-table-button-active-bg`, `--lr-chart-data-table-toggle-hover-bg`,
 `--lr-chart-data-table-toggle-active-bg`, `--lr-chart-reset-zoom-button-hover-bg`,
 `--lr-chart-reset-zoom-button-active-bg`, `--lr-chart-canvas-hover-outline-width`, and
-`--lr-chart-pattern-step`, plus `--lr-chart-legend-side-max` — all inherited from `LyraChart`, identical in meaning and default (see
+`--lr-chart-canvas-hover-outline-color`, `--lr-chart-pattern-step`, plus `--lr-chart-legend-side-max` — all inherited from `LyraChart`, identical in meaning and default (see
 `lr-chart` above); each of the eight variants below reads the same set, so one rule retunes them
 together. The mirrored hooks are `--border-color-1`,
 `--border-color-2`, `--border-color-3`, `--border-color-4`, `--border-color-5`,

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

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [llms-full.txt](../../llms-full.txt)
 - **Deprecations** none
 - **Optional peers** `@sgratzl/chartjs-chart-boxplot`, `chart.js` — see `llms/peers.md`
-- **Themeable via** 12 parts, 13 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 12 parts, 14 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`
 
 ---
@@ -19,6 +19,12 @@
 Box-and-whisker chart from a precomputed five-number summary (no raw sample data sent to the
 browser). Does **not** extend `LyraChart` — a deliberately bespoke API.
 
+With `IntersectionObserver` available, canvas construction waits for its first delivered visibility
+decision. An off-screen box plot stays unconstructed until visible. Without the observer, drawing
+starts when the peers and canvas are ready; an empty delivered callback retains the visible
+fallback. Peer loading and accessible DOM can settle while visibility is pending. These rules also
+apply when the component reconnects.
+
 **Properties:**
 - `labels: readonly string[] = []` (attribute: false)
 - `datasets: readonly LyraBoxPlotSeries[] = []` (attribute: false) — each series contains readonly
@@ -48,8 +54,9 @@ browser). Does **not** extend `LyraChart` — a deliberately bespoke API.
 - `formatter?: LyraChartFormatter`, `valueFormatter?: LyraChartValueFormatter` — numeric axis,
   tooltip, table, summary, and export formatting. The context-object formatter receives the
   family-wide `spoken` surface for the generated summary and `export` for CSV cells; the legacy
-  positional formatter continues to receive `table` for both compatibility paths. The
-  context-object formatter takes precedence
+  positional formatter receives `table` for the spoken/export compatibility paths, its normal
+  surface name for axis, tooltip, and table work, and no fallback for a `visual` context. The
+  context-object formatter takes precedence.
 - `showDataTable: boolean = false` (attribute `show-data-table`) — reveals the accessible data table
 - `dataTableToggle: boolean = false` (attribute `data-table-toggle`, new in 11.0.0) — renders a
   localized disclosure button (`part="data-table-toggle"`) above the data table so a *sighted*
@@ -57,8 +64,9 @@ browser). Does **not** extend `LyraChart` — a deliberately bespoke API.
   consumers wrapping a duplicated table in their own `<details>`. With the toggle on,
   `showDataTable` becomes the disclosure's **initial** state rather than its whole behavior; the
   table stays in the DOM in both states, so assistive technology never loses it, and the button
-  carries `aria-expanded` plus `aria-controls` pointing at the `data-table` wrapper. Unset, nothing
-  renders and behavior is identical to before.
+  carries `aria-expanded` plus `aria-controls` pointing at the `data-table` wrapper. A supplied
+  `slot="data-table"` follows this same disclosure state. Unset, nothing renders and behavior is
+  identical to before.
 
 **Methods:** `exportData('csv'|'png')` returns spreadsheet-safe summary rows or the current canvas
 PNG data URL. `refreshTheme()` re-reads canvas theme custom properties after an ancestor theme
@@ -112,7 +120,8 @@ that sets no `color` is assigned an entry from the same `--lr-color-chart-1..8`
 so `--lr-theme-color-chart-*` retheming reaches box plots too. `--lr-chart-pattern-step`
 (default `var(--lr-space-2xs)`) sizes the forced-colors legend texture and
 `--lr-chart-canvas-hover-outline-width` (default `var(--lr-border-width-thin)`) sizes the `canvas`
-hover outline, `--lr-chart-legend-item-active-bg` and `--lr-chart-legend-item-hover-bg` retune the
+hover outline; `--lr-chart-canvas-hover-outline-color` (default `var(--lr-chart-grid-color)`) sets
+its color. `--lr-chart-legend-item-active-bg` and `--lr-chart-legend-item-hover-bg` retune the
 pressed and hovered legend rows, and `--lr-chart-legend-side-max` caps a side legend — the same tokens and defaults as
 `lr-chart`. Its own `dataTableToggle` disclosure button carries box-plot-namespaced hooks rather
 than inheriting the chart pair, since its stylesheet is not a re-export:

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

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [llms-full.txt](../../llms-full.txt)
 - **Deprecations** none
 - **Optional peers** `chart.js`, `chartjs-plugin-annotation`, `chartjs-plugin-datalabels`, `chartjs-plugin-zoom` — see `llms/peers.md`
-- **Themeable via** 16 parts, 35 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 16 parts, 36 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Documented with** `lr-line-chart`, `lr-bar-chart`, `lr-pie-chart`, `lr-doughnut-chart`, `lr-radar-chart`, `lr-polar-area-chart`, `lr-scatter-chart` (same section below)
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
@@ -58,7 +58,7 @@ failure transition is announced through the shared document-level light-DOM asse
 `--lr-chart-data-table-button-active-bg`, `--lr-chart-data-table-toggle-hover-bg`,
 `--lr-chart-data-table-toggle-active-bg`, `--lr-chart-reset-zoom-button-hover-bg`,
 `--lr-chart-reset-zoom-button-active-bg`, `--lr-chart-canvas-hover-outline-width`, and
-`--lr-chart-pattern-step`, plus `--lr-chart-legend-side-max` — all inherited from `LyraChart`, identical in meaning and default (see
+`--lr-chart-canvas-hover-outline-color`, `--lr-chart-pattern-step`, plus `--lr-chart-legend-side-max` — all inherited from `LyraChart`, identical in meaning and default (see
 `lr-chart` above); each of the eight variants below reads the same set, so one rule retunes them
 together. The mirrored hooks are `--border-color-1`,
 `--border-color-2`, `--border-color-3`, `--border-color-4`, `--border-color-5`,

package/llms/components/lr-button.md

@@ -24,6 +24,13 @@ light-DOM form's submission on its own. They remain default actions of the compo
 runs, while `stopPropagation()` alone does not. Canceling the form's later `submit` or `reset`
 event remains an independent veto point.
 
+External descriptions follow the current source element identity when an element with the same ID
+replaces it, when a source is removed or reinserted, and when the control reconnects or moves to
+another document. Host-root lookup and ordering follow the current `aria-describedby` list,
+including unresolved IDs and duplicates. Switching between native button and anchor modes keeps the
+relationship on the current action. Existing accessible names and `aria-controls` relationships
+retain their separate contracts.
+
 Set `href` to a safe link URL and the root renders as a real `<a part="base" href=…>` instead — a
 link styled as a button (e.g. a CTA). Native navigation is then the activation, so the submit/reset
 handling and `type` have no effect in that mode. A disabled link button (its own `disabled` or an
@@ -340,9 +347,10 @@ box no matter what tier or override is in play.
   an ancestor `<form>.elements` the same way `wa-button` does — a sibling text field's own
   Enter-to-submit lookup (which scans `form.elements` for a `type === 'submit'` control) finds it.
 - **`SubmitEvent.submitter` is not this element** whenever `name`/`value` or any `form*` override is
-  set: it is the transient native `<button>` described above, which has already been removed from
-  the DOM by the time a `submit` listener runs. Read the submitted entry from the `FormData`, or
-  the override off your own component, rather than identity-checking the submitter.
+  set: it is the transient native `<button>` described above. That native submitter remains
+  connected throughout synchronous `requestSubmit()` handling, so a `submit` listener can read
+  its `name`, `value` and `form*` fields and construct `FormData` with it. It is removed after
+  submission handling returns; its identity is distinct from the `lr-button` host.
 - The `form*` overrides and `type` are all inert while `href` renders the anchor — native navigation
   is the activation there, and an anchor has no submit/reset concept.
 

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

@@ -21,6 +21,10 @@ plain text, including its title, start/end time, location, and description. RFC
 remain all-day dates rather than fabricated midnight times, and an all-day `DTEND` is displayed as
 the exclusive boundary it represents (14–17 renders as 14–16). No HTML is injected.
 
+Valid early all-day dates, including years `0001`, `0099`, and `0100`, retain their UTC calendar
+year when parsed through `ical.js`; the exclusive `DTEND` display rule remains unchanged. The peer
+may normalize malformed raw date fields before Lyra receives them.
+
 **Properties:** `src: string = ''`, `name: string = ''`, and `maxHeight: string = ''` (attribute
 `max-height`); invalid CSS
 `max-height` values, declaration breaks, and `url()` are ignored. A host `aria-label` takes

package/llms/components/lr-calendar.md

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [llms-full.txt](../../llms-full.txt)
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 16 parts, 6 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 16 parts, 12 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`
 
 ---
@@ -18,12 +18,19 @@
 
 Responsive month calendar with event markers and an agenda view.
 
+Early ISO dates such as `0001`, `0099`, and `0100` retain their authored local year in the month
+grid and month navigation. Valid colored agenda actions preserve their foreground/background pairing
+through hover and press, with the existing state tokens remaining overridable. Arbitrary caller
+colors still require the caller to choose an accessible contrast pair.
+
 **Properties:**
 
 - `events: CalendarEvent[] = []` (attribute: false) — `{ readonly id?, readonly date, readonly
-title, readonly color?, readonly data? }`; `date` is an ISO `YYYY-MM-DD` string and `color` is
-  sanitized before being used as the marker background. The former ignored `start`/`end` fields
-  are not part of the contract; use one event per displayed date
+title, readonly color?, readonly data? }`; `date` accepts an ISO `YYYY-MM-DD` string, finite epoch
+  milliseconds, or a valid `Date`, then normalizes to the displayed ISO day. Invalid date/title rows
+  are omitted; `lr-event-select.detail.event` remains the original admitted object. `color` is
+  sanitized before use as the marker background. The former ignored `start`/`end` fields are not
+  part of the contract; use one event per displayed date
 - `value: string = ''` — the selected ISO date
 - `viewDate: string` (attribute `view-date`, defaults to the 1st of the current month) — the visible
   month; an unparseable value falls back to the current month
@@ -65,6 +72,10 @@ and `--lr-calendar-day-min-block-size-narrow` (default `var(--lr-size-4rem)`, ap
 day's background; `--lr-calendar-day-outside-color` (default `var(--lr-color-text-quiet)`) and
 `--lr-calendar-day-outside-bg` (default `var(--lr-color-surface)`) for adjacent-month days; and
 `--lr-calendar-day-today-outline-color` (default `var(--lr-color-brand)`) for today's outline.
+`--lr-calendar-nav-hover-bg`, `--lr-calendar-nav-active-bg`, `--lr-calendar-day-hover-bg`,
+`--lr-calendar-day-active-bg`, `--lr-calendar-agenda-event-hover-bg`, and
+`--lr-calendar-agenda-event-active-bg` independently theme navigation, day, and agenda-event
+hover/pressed states through inheritable inline fallbacks.
 These state hooks use inline fallbacks at their paint rules, so an application theme can set them
 on an ancestor. They keep persistent selection, outside-month chrome, and today's outline
 independent from shared tokens that also drive unrelated component states.

package/llms/components/lr-carousel.md

@@ -27,6 +27,11 @@ native or authored semantics, and an explicit `role`, `aria-roledescription`, or
 temporarily makes off-page slides inert and aria-hidden, then restores their retained author state
 when they become visible, are removed, or the carousel disconnects.
 
+**Keyboard:** focus the `scroll-container` viewport to navigate with Arrow keys (horizontal LTR/RTL
+or vertical), Home, and End. Keys originating in a native input, textarea, contenteditable surface,
+or supported custom control remain owned by that editor, including when the editor is the assigned
+slide itself; they do not change the active slide or move focus away from it.
+
 **Properties:**
 
 - `currentSlide: number = 0` (attribute `current-slide`, reflected) — zero-based index of the first

package/llms/components/lr-chart.md

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md); family-wide breaking-change summaries: [llms-full.txt](../../llms-full.txt)
 - **Deprecations** none
 - **Optional peers** `chart.js`, `chartjs-plugin-annotation`, `chartjs-plugin-datalabels`, `chartjs-plugin-zoom` — see `llms/peers.md`
-- **Themeable via** 16 parts, 35 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 16 parts, 36 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`
 
 ---
@@ -21,6 +21,10 @@ Chart.js wrapper used directly and by the eight typed Chart.js tags plus `lr-his
 series surface and a raw Chart.js `config` passthrough (mirrors Web Awesome's `wa-chart` `config`
 property).
 
+For horizontal scalar bars, tooltip values come from parsed x rather than the category y, including
+an effective raw `config.options.indexAxis` override. Both formatter APIs follow this rule;
+structured points retain their y-value formatting.
+
 **Properties:**
 - `type: LyraChartType = 'bar'` — `LyraChartType = 'line' | 'bar' | 'scatter' | 'pie' | 'doughnut' |
   'radar' | 'polarArea' | 'bubble'` — every named default used by a typed `lr-*-chart` is
@@ -86,7 +90,9 @@ property).
     splitting the series in two.
   - `segmentColors` colors each *segment* (the line drawn between two consecutive points) by the
     segment's **starting** point index, so `['red', 'green']` over 3 points paints the first
-    segment red and the second green; a shorter array cycles. Wired to Chart.js's
+    segment red and the second green; a shorter array cycles. When rows are sampled, each
+    represented segment retains the original source starting-point index modulo the palette length.
+    Wired to Chart.js's
     `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.
@@ -117,7 +123,10 @@ property).
 - `formatter?: LyraChartFormatter` (attribute: false) — the family-wide context-object formatter:
   `({ value, surface, datasetIndex?, index?, label?, seriesLabel?, statistic? }) => string`.
   `surface` identifies `visual`, `spoken`, `export`, `tick`, `tooltip`, `legend`, or `table`.
-  It takes precedence over the legacy positional `valueFormatter` where both are supplied.
+  `statistic`, when present for a structured datum or stack total, is one of `x`, `y`, `r`,
+  `min`, `q1`, `median`, `q3`, `max`, or `total`. It takes precedence over the legacy positional
+  `valueFormatter` where both are supplied. The legacy callback remains a visual/table compatibility
+  hook; use `formatter` when a generated spoken value or CSV cell must use the same unit text.
 - `area: boolean = false` — chart-wide default for whether line-type series fill the region under
   their line; a series's own `fill` overrides it, rendered with a translucent version of its color
 - `zoom: boolean = false` — wheel/drag/pinch zoom on the `x` axis only (pan disabled, and the zoom
@@ -172,8 +181,10 @@ property).
   consumers wrapping a duplicated table in their own `<details>`. With the toggle on,
   `showDataTable` becomes the disclosure's **initial** state rather than its whole behavior; the
   table stays in the DOM in both states, so assistive technology never loses it, and the button
-  carries `aria-expanded` plus `aria-controls` pointing at the `data-table` wrapper. Unset, nothing
-  renders and behavior is identical to before.
+  carries `aria-expanded` plus `aria-controls` pointing at the `data-table` wrapper. Until the
+  reader activates it, the disclosure follows `showDataTable`; afterwards the reader's selected
+  state remains authoritative for that mounted chart. A supplied `slot="data-table"` follows this
+  same disclosure state. Unset, nothing renders and behavior is identical to before.
 - `chartArea: LyraChartArea | undefined` (readonly) — current Chart.js chart-area geometry in
   canvas-local coordinates (`top`, `left`, `right`, `bottom`, `width`, `height`), when a chart is
   drawn
@@ -328,7 +339,8 @@ plot in narrow containers;
 declaration on a DOM element (the outline is painted by the stylesheet, not by Chart.js), so it is
 consumed directly with no `getComputedStyle` bridging; it is an inline `var()` fallback at the point
 of use, so it can be set on the element or any ancestor, and left unset the outline is exactly the
-`--lr-border-width-thin` it always was.
+`--lr-border-width-thin` it always was. `--lr-chart-canvas-hover-outline-color` (default
+`var(--lr-chart-grid-color)`) independently controls that outline's color.
 
 `--lr-chart-pattern-step` (default `var(--lr-space-2xs)`) is the tile size of the texture painted on
 `[part="legend-swatch"]` while `forced-colors: active` matches — the legend half of the non-colour
@@ -421,9 +433,12 @@ announced. In particular, unavailable data labels do not remove generated table
   The raw `config` passthrough is deep-merged with `__proto__`/`constructor`/`prototype` keys skipped
   unconditionally, so a JSON-sourced `config` (e.g. parsed from an API response) can't reach up and
   pollute `Object.prototype` through the merge.
-- lazy-redraw + change gating: an `IntersectionObserver` gates `draw()` — while the host is scrolled
-  off-screen, property changes that would otherwise trigger a Chart.js redraw are skipped (and a
-  single redraw fires once it re-enters the viewport). Independently, `updated()` only reaches
+- lazy-redraw + change gating: with `IntersectionObserver` available, canvas construction waits
+  for its first delivered visibility decision. Off-screen charts remain unconstructed until
+  visible, and later off-screen property changes skip redraws until visibility returns. Without
+  the observer, drawing starts when the peer and canvas are ready. An empty delivered callback
+  retains the visible fallback. Peer loading and accessible DOM may settle while visibility is
+  pending. Independently, `updated()` only reaches
   Chart.js when at least one of `type`, `labels`, `datasets`, `description`, `grid`, `indexAxis`,
   `label`, `hiddenDatasets`, `legendPosition`, `min`, `max`, `plugins`, the internal resolved auto legend
   position, `valueFormatter`, `formatter`, `area`, `height`, `xLabel`, `yLabel`, `y2Label`, `beginAtZero`,

package/llms/components/lr-chat-composer.md

@@ -39,7 +39,8 @@ reveals the invalid state, and `form.reset()` clears the touched presentation.
 - `minRows: number = 1` (attribute `min-rows`) — floored to `1` at render time
 - `maxRows: number = 8` (attribute `max-rows`) — floored to at least `minRows`
 - `status: ChatComposerStatus = 'idle'` (reflected) — `'idle' | 'sending' | 'streaming'`; drives the
-  built-in button's icon/label (send vs. stop) and whether Enter still submits
+  built-in button's icon/label (send vs. stop) and whether Enter still submits. Invalid direct or
+  attribute values normalize and reflect as `idle`.
 - `frame: ChatComposerFrame = 'card'` (reflected) — container treatment, in the library-wide `frame`
   vocabulary (`'card' | 'plain'`; `ChatComposerFrame` is an alias of the shared `LyraFrame`).
   `'plain'` drops `[part="base"]`'s border, background, padding and corner radius so a composer

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

@@ -27,6 +27,10 @@ else). No built-in copy button is rendered — slot a copy control into `actions
 `<lr-code-block>`'s copy-affordance contract for anything listening at the conversation-surface
 level).
 
+Compose `lr-copy-button` in `actions` with its `value` set to the intended message source. The shell
+does not infer that source or write the clipboard itself; the composed control emits success only
+after the write fulfills.
+
 **Properties:**
 
 - `messageRole: ChatMessageRole = 'assistant'` (`'user' | 'assistant' | 'system'`, attribute

package/llms/components/lr-checkbox.md

@@ -20,6 +20,9 @@ A boolean form control. `role="checkbox"` with an `aria-checked` that can also b
 visual box/checkmark. Structurally the same idea as `<lr-switch>` (form-associated via
 `ElementInternals`, click and Space toggle) but with checkbox semantics.
 
+Removing `error-text` safely omits the message while preserving native `null` property readback.
+Explicit empty text stays empty; later supplied text renders normally.
+
 **Properties:**
 
 - `checked: boolean = false` — the live, non-reflecting state

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

@@ -24,6 +24,9 @@ clicking its remove (×) button only fires `lr-remove` — the chip never remove
 on its own interaction, the same contract `<lr-attachment-chip>`/`<lr-conversation-item>`
 already follow.
 
+Collapsed groups reapply `max-visible` when assigned children are replaced or reordered at the same
+count, preserving authored hidden/inert state and releasing departed visibility leases.
+
 **Two breaks in 8.0.0.** `tone` is now `variant`, with no alias — one concept, one spelling,
 library-wide. And a chip is **no longer a pill by default**: `--lr-chip-radius` used to be
 `var(--lr-radius-pill)` unconditionally, is now `var(--lr-radius)` (a rounded rectangle), and the

package/llms/components/lr-chip.md

@@ -24,6 +24,9 @@ clicking its remove (×) button only fires `lr-remove` — the chip never remove
 on its own interaction, the same contract `<lr-attachment-chip>`/`<lr-conversation-item>`
 already follow.
 
+Collapsed groups reapply `max-visible` when assigned children are replaced or reordered at the same
+count, preserving authored hidden/inert state and releasing departed visibility leases.
+
 **Two breaks in 8.0.0.** `tone` is now `variant`, with no alias — one concept, one spelling,
 library-wide. And a chip is **no longer a pill by default**: `--lr-chip-radius` used to be
 `var(--lr-radius-pill)` unconditionally, is now `var(--lr-radius)` (a rounded rectangle), and the