@aceshooting/lyra-ui 13.0.1 → 14.1.0

package/llms/components/lr-date-picker.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** 38 parts, 30 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 38 parts, 32 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Documented with** `lr-date-input` (same section below)
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
 
@@ -21,8 +21,37 @@ Mirrors the `<wa-date-picker>`/`<wa-date-input>` 3.11 public API under `lr-`. Bo
 components are **experimental since 3.8**. Values use ISO 8601: `YYYY-MM-DD` (single) or
 `YYYY-MM-DD/YYYY-MM-DD` (range).
 
-The ISO model is proleptic Gregorian in every locale, including years `0000`–`0099` (no JavaScript
-`Date` 1900 remap). Month/day names and visible day/week digits follow the effective locale while
+For `lr-date-input`, host `aria-describedby` targets resolve in the host's root and describe the
+native combobox input through element references, before its existing error and hint descriptions.
+Replacement, removal, reinsertion, newly resolved IDs, reconnect, and adoption update those
+relationships. Removing `label`, `hint`, or `error-text` safely omits that copy while preserving
+`null` property readback; later supplied values render normally.
+
+`lr-date-input`'s `clearLabel`, `openLabel`, and `dialogLabel` retain their initial defaults (`''`,
+`''`, and `'Choose date'`). Omitted labels localize; explicitly supplied text, built-in English
+labels, and empty strings win over `.strings`. Attribute removal restores localization while
+preserving `null` readback. The composed calendar applies the same range endpoint and
+inclusive-length admission rules as the standalone picker.
+
+An authored host `aria-label` names an enclosing calendar group. Individual month and selection
+grids retain their distinct generated period names; changing or removing the purpose label updates
+the group without changing a caller-authored host role. Removing the `value` attribute renders an
+empty selection safely while preserving `null` readback; a subsequent valid value works normally.
+
+Live constraints repair roving state without moving focus from an unrelated control. If a focused
+cell becomes unavailable, focus recovers onto an enabled cell. Explicit distant bounds seed the
+bounded automatic search within the permitted domain; a genuinely empty domain has no enabled roving
+stop. Selected day and range-endpoint buttons retain their foreground/background pairing during
+hover and press; author state-token overrides remain available. Month/year/decade state buttons
+retain the common typography, padding, border reset, and minimum action size.
+
+The `calendar-core.ts` helper `formatISO()` returns an empty string for invalid dates or years
+outside `0000`–`9999`, so generated ISO anchors never advertise an unsupported signed or five-digit
+year.
+
+The ISO model is proleptic Gregorian in every locale and supports years `0000`–`9999`, including
+`0000`–`0099` without JavaScript's `Date` 1900 remap. Navigation anchors remain within that domain;
+moving past either boundary leaves a valid roving stop and does not change the selected value. Month/day names and visible day/week digits follow the effective locale while
 formatters explicitly select the Gregorian calendar. `lr-date-input` uses locale `formatRange()`
 for range presentation and normalizes locale digits plus bidi marks before parsing, so its own
 Arabic/Persian display round-trips to the same ISO value.
@@ -50,12 +79,20 @@ Inline month-grid calendar, not form-associated (used standalone or embedded ins
   tell them apart. A reversed preset normalizes; a malformed one is ignored rather than clearing the
   current value, so a bad entry in a config-driven list never reads as "the user picked nothing".
   Non-array runtime assignments normalize to the empty collection, and null/non-object entries in
-  an otherwise valid array are omitted from the rendered row rather than aborting the calendar.
+  an otherwise valid array are omitted from the rendered row rather than aborting the calendar. Empty and
+  whitespace-only labels are also omitted, preserving named siblings. Explicit endpoints clamp to
+  `min`/`max` before admission. Both endpoints must be selectable, and the inclusive length must
+  satisfy `minRange`/`maxRange`; invalid outcomes render disabled and do not emit value events.
+  Interior dates need not all be enabled. A same-day manual completion obeys those same inclusive
+  length limits. Long preset labels wrap in narrow allocations, including unbroken text and RTL.
   The active button carries `aria-pressed="true"` and `data-active`. Deliberately the same
   `label`/`start`/`end` shape as `<lr-time-range>`'s `TimeRangePreset`, so the library has one
   preset vocabulary rather than two — the only difference is the unit (ISO dates, not numbers)
 - `appliedPreset: LyraDateRangePreset | undefined` (read-only, new in 11.1.0) — the preset whose
-  button produced the current `value`, or `undefined` when the range was picked by hand. Read it
+  button produced the current `value`, or `undefined` when the range was picked by hand, cleared, or changed externally.
+  `clear()` removes identity before synchronous `input`/`change` listeners run; an external value
+  change removes identity silently. An accepted preset retains its exact caller-owned source
+  identity through its own update. Read it
   inside your own `change`/`input` handler. It exists because a dashboard filter has to persist
   *which* preset is active rather than the pair it froze to: "Last 7 days" must still mean the last
   7 days after tomorrow's reload. That fact is not recoverable from `value` — re-deriving it by
@@ -91,8 +128,11 @@ Inline month-grid calendar, not form-associated (used standalone or embedded ins
 - `weekdayFormat: 'narrow'|'short'|'long' = 'short'` (attribute `weekday-format`, reflected)
 - `withOutsideDays: boolean = false` and `withWeekNumbers: boolean = false` (reflected)
 
-Lyra retains the additive `previousLabel`/`nextLabel` localized accessible-label overrides and
-the `selection` range getter.
+Lyra retains the additive `previousLabel`/`nextLabel` accessible-label overrides and the `selection`
+range getter. Their initial readback remains `'Previous month'` and `'Next month'`; omitted labels
+localize, while explicit text, the built-in English labels, and empty strings win over locale and
+`.strings` copy. Removing either label attribute restores localized omission while preserving
+`null` property readback.
 
 **Methods:** `clear()`, `focus(options?)`, `goToToday()`, and
 `goToDate(date: string | Date)`. Valid navigation dates are clamped to `min`/`max`; invalid values
@@ -388,6 +428,10 @@ and `dateTimeFormat(locale, options)`.
   currently-selected paint for a `presets` quick-range button. Defaults are
   `var(--lr-color-brand-quiet)`, that hover colour mixed by `--lr-color-mix-active`, and
   `var(--lr-color-brand)` respectively.
+- `--lr-date-picker-preset-selected-border` (default `var(--lr-color-brand)`) and
+  `--lr-date-picker-preset-selected-color` (default `var(--lr-color-on-brand)`) independently
+  theme a selected preset's border and foreground; the selected background token controls only its
+  background.
 - `--lr-date-picker-title-hover-color`, `--lr-date-picker-title-active-color`,
   `--lr-date-picker-title-active-bg`, and `--lr-date-picker-title-active-radius` — Month-title
   hover/press paint and pressed shape; defaults to brand, brand, brand-quiet, and

package/llms/components/lr-details.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-dialog.md

@@ -18,6 +18,10 @@
 
 General-purpose modal/overlay plus a promise-based confirmation helper built on top of it.
 
+Removing `label` safely omits its fallback title. Open dialog and drawer names follow supported name
+and exclusion attribute changes on direct unslotted headings, while host naming retains precedence;
+nested and `slot=""` headings remain outside automatic discovery.
+
 ### `lr-dialog`
 
 A modal/overlay: `role="dialog"`, focus-trapped while open, dismissible via Escape or (opt-in) a

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

@@ -48,6 +48,12 @@ First-party invention (no Web Awesome equivalent).
   highlighting the diff. `Infinity` relaxes this line-count ceiling, but the fixed aggregate
   character and comparison-work ceilings remain in force.
 
+Grammar entries are read from own enumerable data fields into a bounded frozen map. A getter,
+unreadable field, non-enumerable field, or malformed proxy branch is skipped without preventing a
+later valid grammar from being used; grammar values themselves remain opaque to the component.
+Non-enumerable names do not consume language slots, but every inspected name counts toward the
+20,000 structural ceiling.
+
 **Events:**
 
 - `lr-copy` (`detail: LyraClipboardWriteSuccess`, `{ ok: true; text: string }`) — the frozen full

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

@@ -28,7 +28,10 @@ is absent, it uses the localized comparison label. Dynamic host-label changes up
 - `oldVersion?: DocumentCompareVersion`, `newVersion?: DocumentCompareVersion` (attribute: false) —
   the before/after inputs. `DocumentCompareVersion` extends `DocumentRef`
   (`id`, `name`, `mimeType?`, `uri?`, `version?`) with `text?: string` for diff mode and
-  `highlights?: LyraHighlight[]` for its own preview pane.
+  `highlights?: LyraHighlight[]` for its own preview pane. Each assignment becomes a frozen
+  snapshot: own string `id` and `name` are required or that pane is unset; valid string optional
+  fields are retained and other values are omitted. Its highlights use the shared snapshot too, so
+  mutation requires reassignment.
 - `view: 'diff' | 'side-by-side' = 'diff'` (reflected) — one inline text diff or two rendered
   preview panes. Invalid property or attribute values normalize to `diff` and repair the reflected
   attribute.
@@ -37,7 +40,8 @@ is absent, it uses the localized comparison label. Dynamic host-label changes up
   repair the reflected attribute.
 - `copyable: boolean = false` — forwards the diff copy action.
 - `language: string = ''`, `languages?: Record<string, ShikiLanguageInput>` (the latter
-  attribute: false) — optional syntax highlighting forwarded to the diff.
+  attribute: false) — optional syntax highlighting forwarded to the diff. A runtime non-string
+  `language` is treated as `''` without coercion.
 - `syncScroll: boolean = true` (attribute `sync-scroll`) — proportionally mirrors either
   side-by-side pane's scroll fraction to the other. The true-default converter accepts the literal
   `sync-scroll="false"`.

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

@@ -20,6 +20,10 @@ Controlled searchable and filterable document inventory with versions, tags, own
 sorting, and bulk selection. It composes the table's bounded 100-row default, so a large document
 collection stays reachable through pagination without mounting an unbounded grid.
 
+Own `tags: undefined` is treated like omitted tags; malformed tag arrays and entries remain invalid.
+Removing `search-term` clears search filtering without rewriting its `null` property readback; an
+explicitly empty query also clears filtering and a later query applies normally.
+
 **9.0 migration:** `lr-filter-change.detail.text` is now `searchTerm`, backed by the public
 `searchTerm`/`search-term` axis. Replace `sortDirection: 'ascending'|'descending'` with
 `sortDir: 'asc'|'desc'`; document sorting now uses the same cancelable `lr-sort-request` followed

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

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md)
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 18 parts, 10 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 18 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`
 
 ---
@@ -20,6 +20,9 @@ A format-dispatching viewer for one document/attachment, plus the visual state m
 server-side conversion a host app runs in front of it. First-party invention (no Web Awesome
 equivalent).
 
+Fitting images remain centered; overflowing nonzoomable images begin inside the reachable body
+scroll range, so their top and bottom are available.
+
 Format dispatch is intentionally minimal: only `text/*`/`application/json` (a plain, scrollable
 `<pre>` — no syntax highlighting; compose `<lr-code-block>` yourself via the `unsupported` slot for
 that) and `image/*` (a contained `<img>`) render inline. Everything else — PDF, office documents,
@@ -55,7 +58,10 @@ image path — and the generic fallback simply omits `[part="download-link"]` en
   still in progress. Validated per-sink before use — see the URL-safety note above; an unsafe/
   malformed value is treated as if `src` were unusable for that sink, never passed to `fetch()`/
   `<img>`/the anchor.
-- `mimeType: string = ''` (attribute `mime-type`) — drives format dispatch (see above).
+- `mimeType: string = ''` (attribute `mime-type`) — drives format dispatch using the case-insensitive
+  MIME essence before parameters. For example, `application/json; charset=utf-8` renders as text.
+  Attribute removal retains `null` readback and is interpreted as an absent format by the renderer;
+  an explicitly empty attribute remains empty, and later valid values restore dispatch.
 - `filename: string = ''` — shown in the header and used as the download link's suggested filename.
 - `alt?: string` — image description. When omitted, the filename/localized image-preview fallback
   is used; an explicit empty string keeps a decorative preview's `alt=""` intact.
@@ -82,7 +88,11 @@ image path — and the generic fallback simply omits `[part="download-link"]` en
 - `highlights: readonly LyraHighlight[] = []` (attribute: false) — display-only `region` highlights painted
   over the image-format preview; ignored for the `text`/`generic` formats. IDs are trimmed and
   required to be nonempty, with the first record retained when IDs repeat. A rectangle renders only
-  when `x`/`y`/`width`/`height` are finite numbers and both dimensions are nonnegative.
+  when `x`/`y`/`width`/`height` are finite numbers and both dimensions are nonnegative. Image-region
+  geometry is captured when `highlights` is assigned: an invalid or accessor-backed `region` anchor
+  is ignored, and mutating an accepted anchor later does not move its painted region. Reassign
+  `highlights` to update it; the original public anchor identity remains available for
+  reference-based `scrollToAnchor()`.
 - `activeHighlightId: string | null = null` (attribute `active-highlight-id`) — the `highlights`
   entry, if any, currently treated as active (`data-active` on its `region-highlight`).
 - `anchorKinds: readonly LyraAnchor['kind'][] = ['region']` (this viewer's supported
@@ -144,7 +154,11 @@ every other element that read them. The tone-specific resting border and hover t
 `--lr-document-preview-highlight-accent-color`, `--lr-document-preview-highlight-success-color`,
 `--lr-document-preview-highlight-warning-color`, `--lr-document-preview-highlight-danger-color`,
 and `--lr-document-preview-highlight-neutral-color` (defaulting respectively to the matching
-brand/success/warning/danger/neutral color tokens). Plus shared tokens
+brand/success/warning/danger/neutral color tokens). `--lr-document-preview-download-link-hover-bg`
+defaults to `color-mix(in oklab, var(--lr-color-brand), var(--lr-color-mix-partner)
+var(--lr-color-mix-hover))`; `--lr-document-preview-download-link-active-bg` uses the same mix with
+`var(--lr-color-mix-active)`, styling the native download action's hover and pressed backgrounds.
+Plus shared tokens
 `--lr-color-border`, `--lr-radius`, `--lr-color-surface`, `--lr-space-s/-m/-l/-xs`,
 `--lr-color-text`, `--lr-color-text-quiet`, `--lr-color-danger`, `--lr-color-brand`,
 `--lr-color-on-brand`, `--lr-focus-ring-width/-color/-offset`, `--lr-transition-fast`.

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

@@ -9,7 +9,7 @@
 - **Release history** [CHANGELOG.md](../../CHANGELOG.md)
 - **Deprecations** none
 - **Optional peers** none
-- **Themeable via** 2 parts, 1 custom property — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 2 parts, 3 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`
 
 ---
@@ -20,6 +20,11 @@ A dialog-hosted, format-dispatching full viewer for one document or attachment.
 renderer registry and falls back to `<lr-document-preview>` when no renderer matches the file's MIME
 type. First-party invention.
 
+MIME matching uses the case-insensitive essence before parameters and ignores outer whitespace. An
+extensionless `application/*+xml` file selects the XML renderer when it is registered, including a
+value such as ` APPLICATION/ATOM+XML ; charset=utf-8 `. Exact registry keys retain precedence,
+filename extensions remain a fallback, and the renderer receives the original MIME value.
+
 A host `aria-label` names the nested dialog by attribute presence, including an explicitly empty
 value, without suppressing the visible `name` heading.
 
@@ -35,9 +40,10 @@ value, without suppressing the visible `name` heading.
   anchors/highlights, and download; the scalar `name`, `mimeType`, `src`, `anchor`, `highlights`,
   and `alt` properties resume their legacy behavior when `payload` is reset to `undefined`.
 - `registry?: DocumentRendererRegistry` (attribute: false) — optional per-instance registry
-  override. A native map assignment is copied behind a frozen readonly facade; definition records
-  are cloned and frozen while callback identities are retained. Later source-map or definition
-  mutation is not observed. When unset, the
+  override. Assign either a native map or the result of `createDocumentRendererRegistry()`; both
+  use the same bounded snapshot behind a frozen readonly facade. Definition records are cloned and
+  frozen while callback identities are retained. Later source-map or definition mutation is not
+  observed. Reassigning the same source or retained snapshot leaves the snapshot unchanged. When unset, the
   instance owns an immutable snapshot of the built-ins registered when it was constructed. A later
   module import/registration cannot mutate an existing viewer. A throwing consumer matcher or
   renderer is contained as the localized error state rather than escaping the update.
@@ -79,6 +85,10 @@ polite and assertive sinks, respectively;
 
 **Themeable custom properties:** `--lr-document-viewer-max-height` (default `70vh`) — maximum block
 size of `[part="body"]` before the dialog body scrolls internally.
+`--lr-document-viewer-download-link-hover-bg` defaults to `color-mix(in oklab,
+var(--lr-color-brand), var(--lr-color-mix-partner) var(--lr-color-mix-hover))`, and
+`--lr-document-viewer-download-link-active-bg` uses `var(--lr-color-mix-active)` in that same mix
+for the native download action's hover and pressed backgrounds.
 
 **Renderer registry exports:**
 

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

@@ -68,6 +68,12 @@ resolved keyboard action was activated.
 content. `lr-anchor-result` (`detail: { found }`) — fired after an `anchor` assignment or a
 `scrollToAnchor()` call.
 
+Mammoth's conversion result is usable only when it has own-data `value: string` and an own-data
+`messages` array; an unusable primary result is terminal. From a usable result, the first 100
+message positions are considered, malformed entries are omitted, and valid opaque causes are
+retained in their diagnostics. Sanitized document content remains visible while those non-fatal
+diagnostics are emitted.
+
 **CSS parts:** `base`, `body`, `content`, `spinner`, `error`, `highlight` (a painted `text-quote`
 highlight), `highlight-actions` (keyboard-accessible actions for resolved highlights),
 `highlight-action` (one native highlight activation button), `search-match` (a painted in-document

package/llms/components/lr-doughnut-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-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-dropdown-item.md

@@ -22,6 +22,10 @@ The inline semantic menu mapped from Shoelace's `sl-menu`, plus its action-row e
 wrapping keyboard navigation, type-ahead, and one canonical selection event. It deliberately has no
 trigger, positioned popup, root open state, placement API, or overlay lifecycle.
 
+Removing or disabling the remembered active item repairs the roving stop without taking focus from
+outside controls or the menu's header/footer. If the changed item held actual focus, focus moves to
+a valid survivor or through the existing owner dismissal path when none remain.
+
 For a menu button or other anchored overlay, compose the semantic controller inside
 `<lr-dropdown>`:
 

package/llms/components/lr-dropdown.md

@@ -25,6 +25,9 @@ consumer-supplied `lr-menu` in the default slot becomes that contained engine in
 wrapped in another menu. This supports both Web Awesome's direct-item shape and Shoelace's
 consumer-menu shape.
 
+An open lr-dropdown repositions when its effective host or inherited text direction changes,
+preserving open state without emitting lifecycle events.
+
 **Direct mapped items.** `<lr-dropdown-item>` is the Web Awesome-compatible name for the same row
 implementation as `<lr-menu-item>`. Direct mapped items receive this dropdown's `size` and use its
 contained roving-focus, type-ahead, disabled-skipping, selection, and submenu controller; a

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

@@ -18,7 +18,13 @@
 
 Renders EPUB ebooks through the optional `epubjs` peer. `src` is fetched as an `ArrayBuffer`, and
 epub.js renders the reading area into its stable `mount` element, using an internal iframe for
-chapter content.
+chapter content. A usable book exposes `ready`, `renderTo()`, and `destroy()`, and its rendition
+exposes `display()`, `prev()`, `next()`, `on()`, and `annotations.highlight()`/`remove()`; an absent
+required capability is terminal. Navigation and spine data are optional.
+
+Genuine native `Selection`/`Range` objects from the current chapter iframe are accepted through
+platform accessors, including across document realms. Arbitrary peer-owned accessors remain
+uninvoked, and callbacks from replaced or disconnected books cannot emit stale selections.
 
 **Properties:** `src: string = ''` and `name: string = ''`. A plain `aria-label` attribute on the
 host overrides the reading region's accessible name — by attribute presence, so an explicitly empty
@@ -39,14 +45,17 @@ viewer's supported `LyraAnchor.kind` values for the shared anchor-target contrac
 **Methods:** `getToc()` resolves the EPUB's own navigation document (`book.navigation.toc`,
 populated once `book.ready` resolves) flattened into document-ordered `EbookTocItem[]` (`{ id,
 label, href, level }`, `level` starting at 1 for a top-level entry, `id` falling back to `href`
-when a navigation entry has none), `[]` before a book has loaded. `search(query)` resolves the
+when a navigation entry has none), `[]` before a book has loaded or when navigation is absent. TOC
+projection examines at most 10,000 positions, nodes, and depth 100; malformed entries are skipped
+without preventing later valid entries. `search(query)` resolves the
 match count across every spine section, in document order, via epub.js's own `item.load()`/
 `item.find()`/`item.unload()` (empty/whitespace query behaves like `clearSearch()`; a newer
 `search()` call or a `src` change aborts an in-flight scan; peer output is capped at 10,000
 matches after at most 1,000 spine items and 4,000,000 result code units; queries are capped at 4,096
 code units); `searchNext()`/`searchPrevious()`
 advance/step back through matches (wrapping, resolving `false` when there are none); `clearSearch()`
-clears the query, matches, and painted search annotation.
+clears the query, matches, and painted search annotation. `matchCountExact: false` also reports
+malformed or holey spine/find data and failed section load/unload work, not only a search ceiling.
 
 **Events:** `lr-render-error` with `detail.error` when fetching, opening, or rendering fails;
 `lr-location-change` (`detail: { cfi, href }`) fired from epub.js's own `relocated` event;

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

@@ -29,6 +29,16 @@ An attachment with no filename uses the localized `emailViewerUnnamedAttachment`
 `lr-attachment-open` detail. The fallback resolves while rendering, so changing the locale or
 per-instance `strings` after the message loads updates it without reparsing the message.
 
+When `foldQuotes` is enabled, `search(query)` reveals matching supported plain-text and HTML quoted
+replies before navigating. Reveal uses the shared text index's Unicode normalization, whitespace
+collapse, soft-hyphen removal, locale matching, and query/work bounds, so padded or normalized
+queries reveal the same quote as ordinary matching text. Folding remains opt-in.
+
+Parser output is admitted through a bounded direct-data projection: malformed optional fields,
+recipients, and attachment entries are omitted without discarding later valid siblings. Accepted
+string, `Uint8Array`, and `ArrayBuffer` attachment bytes are copied before use, and every
+`lr-attachment-open` creates a fresh Blob, so later source mutation cannot change event bytes.
+
 Sanitized HTML uses the passive-document profile: anchors, form controls, and custom elements are
 unwrapped to ordinary text/children where safe, remote navigation/resource attributes are removed,
 and an `<a>` itself never remains. Images render only inline base64 GIF, JPEG, PNG, or WebP data;

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

@@ -24,6 +24,17 @@ supplied (an explicit empty array still counts as supplied and skips the auto-lo
 When the filtered set reaches 200 items, the grid automatically windows its visible rows while
 preserving the full option count through `aria-setsize`/`aria-posinset`.
 
+Removing `label`, `hint`, or `error-text` treats the removed value as absent for rendering while
+preserving native attribute-removal property readback. Host `aria-describedby` references resolve in
+the host root onto the value-owning listbox before its local error/hint guidance. Target
+replacement, removal, reinsertion, reconnect, and adoption keep that relationship current. The
+search input keeps its separate description ownership.
+
+`form.reset()` restores the default value and pristine interaction feedback. Required constraints
+and persistent custom validity remain in force; a required-empty value remains invalid. Composing
+key events (`isComposing` or legacy key code 229) remain with text editing and do not navigate or
+pick an emoji.
+
 Ships the same opt-in `label`/`hint`/`errorText` form-control chrome as `lr-select`/
 `lr-color-picker` (props + matching named slots + `form-control`/`form-control-label`/`hint`/
 `error` CSS parts) — left unset, none of that chrome renders.
@@ -35,11 +46,14 @@ can override size-tier fallbacks; a value set directly on the element still wins
 (`custom-error`), `disabled`, and `required`, plus
 `groups: readonly EmojiPickerGroup[] = []` (attribute: false) — readonly `EmojiPickerGroup { key,
 label, emojis: readonly EmojiPickerItem[] }`, readonly `EmojiPickerItem { emoji, name,
-shortcodes? }`; assignment captures a bounded frozen owned snapshot. The search field matches
+shortcodes? }`; assignment captures a bounded frozen owned snapshot, including the current contents
+of reused source item objects. Earlier snapshots remain frozen and unchanged; in-place source edits
+become visible only after an explicit `groups` assignment. The search field matches
 `name` and every `shortcodes` entry, case-insensitively. Consumer group labels render verbatim.
 Groups returned by the built-in loader carry private provenance, letting their fixed emojibase
-headings follow `registerLyraLocale()`/`.strings` without exposing localization keys as consumer
-data. Empty (the default, before the auto-loader
+headings follow `registerLyraLocale()`/`.strings` through filtering and windowed rendering, including
+same-locale `.strings` changes, without exposing localization keys as consumer data. Caller-authored
+headings remain literal even when their keys match built-in groups. Empty (the default, before the auto-loader
 resolves) renders just the search input and the empty state. `accessibleLabel` (`aria-label`)
 forwards a host-supplied accessible name to the internal `role="listbox"` grid. Only omission falls
 back to the visible label or localized default; an explicit `aria-label=""` remains empty.

package/llms/components/lr-empty.md

@@ -18,6 +18,9 @@
 
 First-party "no data" state (no Web Awesome equivalent).
 
+Removing `heading` or `description` safely omits that text; explicit empty values remain empty and
+later values restore the corresponding content.
+
 **Properties:**
 
 - `heading: string = ''`

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

@@ -21,6 +21,9 @@ degree, community chip, plus a built-in "focus in graph" action. Never fetches o
 itself — `lr-entity-select` is a request a host routes into `lr-graph`'s own
 `focusNode(id, options?)`.
 
+The host `aria-level` attribute overrides the internal title heading live. Changing or removing it
+updates that heading without another property change; omission or an empty override uses level 3.
+
 **Properties:**
 
 - `entity: LyraEntity | null = null` (attribute: false) — `LyraEntity { id: string; label: string;

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

@@ -20,6 +20,10 @@ An inline `@entity` mention for agent prose: flow content, keyboard-focusable, w
 preview popover. The knowledge-graph sibling of `lr-citation-badge`, reusing its interaction
 contract wholesale. Carries ids through events only — no entity data resolution, no navigation.
 
+Removing `text` or `type` leaves the property readback as `null` and treats it as absent when
+deriving the button name. Explicit empty strings stay empty, and later valid values restore the
+corresponding label/type text.
+
 **Properties:**
 
 - `entityId: string = ''` (attribute `entity-id`)

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

@@ -22,8 +22,8 @@ Filterable and taggable evaluation-example list with add, remove, import, and ex
 
 - `examples: readonly EvalExample[] = []` (attribute: false) — `EvalExample { id: string; input: string;
 expectedOutput?: string; tags?: readonly string[]; metadata?: Record<string, unknown> }` (exported here).
-  Deliberately its own small shape rather than reusing anything from `src/ai/types.ts` — none of that
-  module's interfaces models "one row of a labeled eval dataset". `input`/`expectedOutput` are plain
+  It is a dedicated dataset-row shape; no shared agent type models a labeled evaluation row.
+  `input`/`expectedOutput` are plain
   strings (not structured payloads), rendered as plain text by every column's `cell()`. Fully
   controlled: add/remove/import/export are all _requests_; the host mutates and passes the array
   back. Empty/blank ids and later duplicate ids are omitted before selection, filtering, mutation requests, and the

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

@@ -123,6 +123,15 @@ downloadBlob(content: string, filename: string, mime: string, ownerDocument?: Do
 
 **Known gotchas:**
 
+- Format options are read from their direct data fields into a frozen list. Accessor-backed, missing,
+  malformed, or throwing descriptor fields are ignored rather than evaluated; later menu rendering
+  and `lr-export` events use that snapshot. The snapshot includes only direct `formatId`, `label`,
+  `description`, and `extension` fields; accepted records are frozen and never reread from the
+  caller. An open multi-format menu is a non-modal overlay owned by the element's
+  current document: only its topmost menu handles that document's Escape, outside pointer, or Tab.
+  It rebinds after document adoption; Escape or a selected export returns focus to its own trigger,
+  while a Tab close permits normal document navigation. Placement uses the current trigger and panel
+  geometry and remains clamped to the current document's viewport.
 - CSV and JSON are the only built-in encoders. To offer XLSX/PDF/etc., pass an
   `LyraExportFormatDescriptor` and handle its `formatId` from `lr-export`; custom formats never trigger a
   download or `lr-export-complete` on their own. A descriptor's optional `extension` is metadata

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

@@ -20,6 +20,13 @@
 A form-associated drag-drop + click-to-browse file dropzone. It stores and renders raw `File[]`;
 no client-side CSV/XLSX/etc. parsing is performed (that's left entirely to the host).
 
+Removing `label` or `hint` consumes it as absent without changing the property's `null` readback. An
+explicit empty string remains empty. Text chrome and label/description associations disappear when
+no corresponding slot or explicit presence hint remains, and a later value restores them. Removing
+the label leaves the localized dropzone instruction available. Disabled file removal buttons,
+including fieldset disablement, retain resting foreground and background under hover and press;
+enabled buttons retain pointer feedback.
+
 **Properties:**
 
 - `multiple: boolean = false` (reflected)
@@ -108,10 +115,8 @@ no client-side CSV/XLSX/etc. parsing is performed (that's left entirely to the h
 `resetValidity()`; reset clears only consumer custom validity and restores current intrinsic
 `required` validity.
 
-**Events:** a user selection or removal emits native bubbling/composed `input`, then `change`;
-programmatic `files` writes are silent. The hidden native picker's own `change` is contained inside
-the shadow root, so a picker selection exposes exactly one post-commit host `change`, not the
-implementation event plus a duplicate. `lr-files` (`detail: LyraFileInputFilesDetail`, with fresh
+**Events:** a user selection or removal emits native bubbling/composed `input`, then exactly one
+host `change`; programmatic `files` writes are silent. `lr-files` (`detail: LyraFileInputFilesDetail`, with fresh
 frozen readonly `files` and `rejected` arrays and frozen rejected-file records, fired on both drop
 and manual file-picker selection; immutable `File` objects retain identity) —
 `LyraFileInputRejectedFile = { readonly file: File; readonly reason: 'type' | 'count' | 'size' | 'directory' | 'read' | 'limit'
@@ -172,10 +177,9 @@ What this changes for you:
 - **Nothing about what the visible text says or where it renders.** `[part="rejection"]`'s text is
   ordinary visible content and stays in the accessibility tree, so a user who reaches it reads it
   normally. Both parts remain the right styling hooks.
-- **A test that asserted `::part(rejection)` had `role="alert"`, or that read announcements out of
-  `::part(status)`, now fails.** Assert against the shared light-DOM region instead — query
-  `[data-lr-live-region="assertive"]` (or `"polite"`) in the document, which is also where every
-  other Lyra announcement lands.
+- **Read announcements from the shared light-DOM region** — query
+  `[data-lr-live-region="assertive"]` or `[data-lr-live-region="polite"]` in the document rather
+  than the styling parts.
 - **A `::part(rejection)[role]`-style selector never matched anyway** — an attribute selector
   cannot follow `::part()`. Nothing that worked before stopped working.
 

package/llms/components/lr-file-tree.md

@@ -19,8 +19,12 @@
 A file-explorer preset over `<lr-tree>` + `<lr-file-icon>`: path-keyed nodes with
 git-status/diff-count badges, lazy directory loading, and select/open events.
 
+An unreadable optional field rejects only that file record; it cannot reserve the path against a
+later valid occurrence. Valid siblings retain their source order within the existing depth and
+inspected-position budgets.
+
 **Properties:** `nodes: readonly FileTreeNode[] = []` (attribute: false; clone-owned/frozen,
-cycle-safe snapshot omitting empty/blank paths and retaining the first duplicate path, bounded to
+cycle-safe snapshot omitting empty/blank paths and retaining the first successfully admitted occurrence of each path, bounded to
 the first 10,000 inspected source positions across 64 descendant levels; reassign after changes),
 `selectedPath: string | null = null` (attribute `selected-path`), and `label?: string` — an
 accessible-name override for the internal `<lr-tree>`, where omission reads back `undefined` and falls

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

@@ -18,6 +18,11 @@
 
 Dashboard filter row that composes Lyra inputs and removable chips, with reset and loading states.
 
+Choice option entries must expose string `value` and `label` data fields; malformed entries are
+omitted independently, while supplied empty strings remain valid. A custom definition requires its
+adapter and a callable `render`; a rejected definition does not reserve its filter ID. Valid
+siblings remain available. Exceptions thrown by an admitted trusted renderer still propagate.
+
 **Properties:**
 
 - `filters: readonly LyraFilterBarFilterDefinition[] = []` (attribute: false) — filter schema in

package/llms/components/lr-flow-canvas.md

@@ -22,6 +22,13 @@ connect interaction. It is readonly by default; opt into editor gestures with `n
 `connectable`, and `droppable`. The component snapshots model inputs instead of retaining mutable
 caller aliases, and reports edit intent for the host to apply.
 
+Input/output handle IDs are reserved only after their complete handle record is admitted; unreadable
+optional labels cannot suppress a later valid handle with the same ID.
+
+Horizontal RTL reflects the coordinate plane while authored cards, generated `lr-flow-node` cards,
+native portable fallback cards and SVG edge labels retain readable content. Explicit physical model
+coordinates remain unchanged.
+
 Flow records and companion payloads are readonly public contracts. Consumers that need the types
 without registering a component can import them from the side-effect-free module:
 
@@ -80,7 +87,7 @@ import type {
 - `decorations: FlowRunDecorations | null = null` (attribute: false) —
   `Record<nodeOrEdgeId, FlowRunDecoration>`, where `FlowRunDecoration` has `status` plus optional
   `progress`, `durationMs`, and `detail`; assignment is detached, deeply frozen, bounded to 10,000
-  keys plus finite nested depth/entry budgets, and invalid status entries are omitted. Reassign the
+  keys plus finite nested depth/entry budgets, and invalid statuses and records with unreadable `status`, `progress`, `durationMs` or `detail` fields are omitted independently, retaining valid neighbors. Reassign the
   record after changes. Usually supplied by `lr-flow-run-status`.
 - `accessibleLabel: string | null = null` (attribute `aria-label`)
 - `viewport` (readonly getter) — a frozen `{ x, y, zoom }` snapshot

package/llms/components/lr-flow-node.md

@@ -39,7 +39,8 @@ owns none of that.
   previews; the border, background, shadow and the `selected`/`status="running"` treatments all stay
 - `inputs: readonly FlowHandle[] = [{ id: 'in' }]`, `outputs: readonly FlowHandle[] = [{ id: 'out'
 }]` (attribute: false) — detached, frozen snapshots of at most the first 10,000 readonly
-  `{ id, label? }` handles; blank ids and later duplicates are omitted first-valid/first-wins;
+  `{ id, label? }` handles; blank ids and later duplicates are omitted first-valid/first-wins
+  (a record rejected for an unreadable optional label does not reserve its ID);
   reassign a collection after changes
 - `orientation: 'horizontal' | 'vertical' = 'horizontal'` (reflected) — which physical edge handles
   render on; mirrors the adopting canvas's own `orientation`