@aceshooting/lyra-ui 14.0.0 → 14.1.0

package/llms/components/lr-date-input.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

package/llms/components/lr-date-picker.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

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

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-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

@@ -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.

package/llms/components/lr-document-viewer.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.

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

@@ -22,6 +22,10 @@ chapter content. A usable book exposes `ready`, `renderTo()`, and `destroy()`, a
 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
 `aria-label=""` still wins over `name`. (There is no matching JS property: the `accessibleLabel`

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

@@ -29,6 +29,11 @@ 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

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-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)

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`

package/llms/components/lr-flow-run-status.md

@@ -26,7 +26,7 @@ poll, or time anything — pure pushed state; `durationMs` is host-computed.
 - `for: string = ''` — id of the target `lr-flow-canvas`; empty resolves to the nearest ancestor
 - `decorations: FlowRunDecorations = {}` (attribute: false) — a detached, deeply frozen readonly
   record bounded to 10,000 keys plus finite nested depth/entry budgets and pushed onto the resolved
-  canvas; invalid status entries are omitted, and consumers reassign the record after changes
+  canvas; invalid statuses and records with unreadable `status`, `progress`, `durationMs` or `detail` fields are omitted independently, retaining valid neighbors, and consumers reassign the record after changes
 - `hideSummary: boolean = false` (attribute `hide-summary`) — omits the "{done} of {total} steps
   complete" strip, keeping only the decoration push
 - `label: string = ''` — accessible name for the summary strip

package/llms/components/lr-format-number.md

@@ -18,6 +18,10 @@
 
 `Intl.NumberFormat` output.
 
+Removing `currency` preserves the removal readback while formatting with the declared USD fallback.
+An explicitly blank currency also keeps its existing USD formatting fallback, and a later valid
+currency takes effect normally.
+
 Shared by all four formatters (`lr-format-number`, `lr-format-date`, `lr-format-bytes`,
 `lr-relative-time`): each is text-only — a `display: inline` host with **no CSS parts, no events, and
 no themeable custom properties of its own** — rendering one formatted string into its shadow root.

package/llms/components/lr-funnel.md

@@ -21,6 +21,10 @@ bar whose length is that stage's share of the **first** stage, read top-to-botto
 drop-off. It sits beside `lr-gauge` and `lr-heatmap` as an analytics primitive rather than a general
 chart type.
 
+When a positive finite stage value divided by a positive finite baseline overflows to `Infinity`,
+the main or comparison data fill clamps to 100%. Nonfinite input normalization, nonpositive-baseline
+behavior, percentage and drop-off text, and overflow border styling keep their existing rules.
+
 It is deliberately not a sorted bar chart: it normalizes to the first stage rather than to the data
 maximum, draws no value axis, and reads as stage-to-stage retention rather than category comparison.
 Reach for `lr-bar-chart`/`lr-lite-chart` when you actually want a value axis and category comparison.

package/llms/components/lr-gauge.md

@@ -18,6 +18,10 @@
 
 Dependency-free SVG radial, full-circle ring, or linear meter (no charting library).
 
+Removing `label` omits the visible SVG label in radial, linear, and ring shapes and restores the
+localized gauge name unless `aria-label` is authored. The property retains removal `null`;
+explicitly empty labels remain empty and later labels render normally.
+
 **Properties:**
 
 - `value: number = 0`

package/llms/components/lr-generation-metrics.md

@@ -20,6 +20,11 @@ A compact, ticking status readout shown alongside an in-progress AI response: el
 count, and token-throughput, plus a built-in Stop button. First-party invention (no Web Awesome
 equivalent). Renders as e.g. `12.3s · 340 tokens · 27 tok/s [Stop]`.
 
+The host handles `lr-stop` by stopping its own producer and setting `status` to `complete`. A
+restart supplies a fresh `startedAt`, resets its token count, and retires the previous producer
+timer. The live example wires this lifecycle on mount, so its first Stop and every Restart take
+effect immediately.
+
 **9.0 identity migration:** `lr-generation-status` → `lr-generation-metrics`,
 `LyraGenerationStatus` → `LyraGenerationMetrics`, and `LyraGenerationStatusEventMap` →
 `LyraGenerationMetricsEventMap`. The old tag, class, event-map name, registration route, and

package/llms/components/lr-graph-query-builder.md

@@ -19,6 +19,12 @@
 Form-associated editor for a typed graph relationship/path query, including entity anchors,
 relationship and node-type filters, hop limits, validation, and saved queries.
 
+When the DOM cannot provide `activeElement`, the builder skips focus restoration while chip removal
+and saved-query updates continue normally. Each minimum/maximum-hop select choice updates the query
+once and emits one `lr-input` with the complete `{ value: GraphQuery }` snapshot. Native value
+events, prefixed value aliases and listbox show/hide lifecycle events from those child selects are
+contained. Programmatic query assignments remain silent.
+
 The normalized `value` present at the first update is the form reset default. Later property writes
 and user edits change only the live query; `form.reset()` restores that initial model, clears
 interaction/touched state and the save-name draft, and retains a caller-set custom validity message

package/llms/components/lr-graph.md

@@ -18,6 +18,12 @@
 
 A force-directed node-link diagram with pan/zoom/drag, built on `d3-force`.
 
+A zero-width canvas link paints neither a stroke nor an arrowhead; its relationship remains in the
+nonvisual topology summary.
+
+In both renderers, roving navigation transfers real focus through nodes, operable links, then
+community hulls; zero-width, fully transparent, and dangling links remain outside that focus order.
+
 **Properties:**
 
 - `nodes: LyraGraphNode[] = []` (attribute: false) — readonly `LyraGraphNode { id: string; label?: string;
@@ -111,7 +117,7 @@ camera; `getNodePosition(id)` returns the current `{ x, y }` in graph-local draw
 **Events:** `lr-node-click` (`detail: { nodeId, x, y }`, where `x` and `y` are the clicked node's current
 local drawing coordinates), `lr-link-click` (`detail: { sourceNodeId, targetNodeId,
 linkId? }`; the optional `linkId` is the stable `LyraGraphLink.id` supplied by the caller), `lr-node-enter`/
-`lr-node-leave` (`detail: { nodeId }`, hover start/end, suppressed while dragging/panning),
+`lr-node-leave` (`detail: { nodeId }`, hover start/end, suppressed while dragging/panning; canvas emits once per hit-identity transition or exit),
 `lr-link-enter`/`lr-link-leave` (`detail: { sourceNodeId, targetNodeId, linkId? }`, same hover contract),
 `lr-node-expand` (`detail: { nodeId }`, a node was double-activated — native `dblclick`, or two
 Enter/Space activations within 500ms — regardless of `LyraGraphNode.expandable`), `lr-community-click`
@@ -222,7 +228,7 @@ localized `part="error"` alert. Install with
   force on the new midpoint and nudges the simulation via `alpha(0.1).restart()`, in addition to
   resizing the rendered `viewBox` — both branches apply independently, so setting `width` and
   `chargeStrength` in the same synchronous batch retunes both, not just one.
-- zoom is bounded via `minZoom`/`maxZoom` (`d3-zoom`'s `.scaleExtent(...)`, live-reactive); pan/
+- zoom is bounded via `minZoom`/`maxZoom` (`d3-zoom`'s `.scaleExtent(...)`, live-reactive in both SVG and canvas); pan/
   zoom/drag are still pointer-only with no keyboard equivalent. Links (`<line part="link">`) are now
   keyboard-operable too (`tabindex="0"`, `role="button"`, `aria-label`, Enter/Space), matching nodes.
 - while the `d3-force`/`d3-drag`/`d3-zoom`/`d3-selection` peers are resolving, the host shows an

package/llms/components/lr-heatmap.md

@@ -33,6 +33,19 @@ Full canvas redraws pause while the host is outside the viewport. Data, locale,
 DPR invalidations remain pending and coalesce into one redraw when the heatmap intersects again;
 environments without `IntersectionObserver` retain eager drawing.
 
+Focus-only updates repaint a bounded neighborhood around the old and new cells, restoring all
+intersected neighboring fills and overlays while preserving the focus-ring geometry. Calendar axis
+pixels intersected by the repaint are restored too.
+
+Changing `domain` or `midpoint` without replacing matrix data preserves absent and nullish cells as
+no data in paint, accessible text, callbacks, and cell events. Missing values still use `-1` in
+default unsigned mode and `NaN` in signed mode; supplied negative signed values remain data.
+
+Invalid authored ramp colors retain the default endpoint fallback. The public `resolveRgb()` helper
+likewise preserves its supplied fallback bytes. These authoring diagnostics are once-per-color
+development warnings and remain silent in production; the separate missing-canvas runtime warning is
+unchanged.
+
 Set `accessibleCells: true` (`accessible-cells`) to opt into a semantic grid backed by a bounded
 window of native buttons. It retains the complete `aria-rowcount`/`aria-colcount` and arrow-key
 navigation model without mounting one node per cell. Buttons use localized `aria-label`s, explicit

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

@@ -22,6 +22,13 @@ slot when a form action is required. Because it is not form-associated, an ances
 `<fieldset disabled>` does not disable it and it is absent from `form.elements`; set `disabled`
 directly on each icon button.
 
+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.
+
 Its public `--lr-icon-button-*` theme inputs stay undeclared on the host, so an ancestor theme
 wrapper can override the built-in fallbacks; a value set directly on the element still wins.
 

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

@@ -21,6 +21,15 @@ landing surface for `region`-anchored citations. Distinct from `<lr-svg-viewer>`
 documents) and `<lr-image-comparer>` (before/after slotted surfaces). Adopts `DocumentAnchorTarget`
 with `anchorKinds: ['region']` only — no text selection is bound.
 
+Disabled fit, rotate and annotate controls retain their resting paint on hover and press. Enabled
+controls keep their token-driven feedback.
+
+The annotation wrapper displays the shared token-driven focus ring in keyboard modality. The ring
+sits inside the wrapper so an image filling the scroll viewport cannot clip it. Annotation commands
+apply when that wrapper itself owns keyboard input. Enter on a highlight button activates that
+highlight without starting or committing an annotation, whether or not a draft exists; wrapper arrow
+commands retain physical image-coordinate semantics in both directions.
+
 **Properties:** `src: string = ''`, `name: string = ''`, `alt?: string`,
 `fit: LyraImageFit = 'contain' | 'width' | 'actual'` (reflected; invalid writes normalize to
 `contain`), `zoom: number = 1` (reflected), `minZoom: number = 0.5` (attribute