@aceshooting/lyra-ui 9.1.1 → 10.0.1

package/llms/components/lr-details.md

@@ -91,11 +91,20 @@ the ladder doesn't cover is a two-line override rather than a fork.
 
 **Events:**
 
-- `lr-expand`, `lr-collapse`, `lr-after-expand`, `lr-after-collapse` — accordion group lifecycle.
+- `lr-expand`, `lr-collapse`, `lr-toggle-request`, `lr-after-expand`, `lr-after-collapse` —
+  accordion group lifecycle.
 - `lr-show`, `lr-hide`, `lr-toggle`, `lr-after-show`, `lr-after-hide` — Details lifecycle only.
 
 On the accordion, `lr-expand` and `lr-collapse` fire before a direct item changes, are cancelable,
-and carry `detail: { item }`. **Changed in 9.0.0:** `item` is now always a `LyraAccordionItem` —
+and carry `detail: { item }`. **New in 10.0.0:** a cancelable `lr-toggle-request`
+(`detail: { collapsed, item }`) fires alongside the matching directional event for every transition,
+including sibling auto-collapses in `single`/`single-collapsible` mode and `collapseAll()`. It carries
+the direction in the detail rather than the event name, matching `<lr-code-block>`/`<lr-chat-message>`'s
+`lr-toggle-request` convention, plus an `item` reference the single-panel siblings do not need (an
+accordion's toggling entity is one of several children, so the event target alone cannot identify it).
+`preventDefault()` on **either** event vetoes the transition — the two are a symmetric veto pair, not
+a primary and a notification. Note `<lr-thinking-panel>`'s own `lr-toggle-request` spells its detail
+`{ expanded }` rather than `{ collapsed }`; the two conventions are not fully unified. **Changed in 9.0.0:** `item` is now always a `LyraAccordionItem` —
 it could previously also be a `LyraDetails`. The exported `LyraAccordionPanel` union that spelled
 that has been removed; use `LyraAccordionItem`. An accepted transition finishes with the
 non-cancelable

package/llms/components/lr-dialog.md

@@ -93,13 +93,18 @@ chrome remains visible. The fallback order appears below.
 - `lr-request-close` — cancelable request from a built-in affordance; detail source is
   `'close-button' | 'keyboard' | 'overlay'`. Veto stops the close lifecycle. Direct `close()` and
   `hide()` calls do not emit this request event.
-- `lr-dialog-close` — cancelable, with `detail: DialogCloseReason`; emitted after `lr-hide`
+- `lr-close` — cancelable, with `detail: DialogCloseReason`; emitted after `lr-hide`. The same name
+  is already used by `<lr-tool-select-dialog>`, `<lr-tool-result-dialog>`, and
+  `<lr-tool-approval-dialog>`, whose own docs describe an identical detail shape, so one listener
+  covers all of them. A listener calling `preventDefault()` vetoes the close. Also fired (with
+  reason `'unmount'`, non-cancelable there) when the dialog is removed from the DOM while still
+  open.
 
 The two `lr-after-*` events are never cancelable.
 
 The open sequence is `lr-show` → `lr-initial-focus` (when focus would move) → `lr-after-show`; the
-direct close sequence is `lr-hide` → `lr-dialog-close` → `lr-after-hide`. A built-in dismissal
-prepends `lr-request-close`. **Both state pre-events fire _before_ the state changes**, so reading
+direct close sequence is `lr-hide` → `lr-close` → `lr-after-hide`.
+A built-in dismissal prepends `lr-request-close`. **Both state pre-events fire _before_ the state changes**, so reading
 `el.open` inside an `lr-show`/`lr-hide` handler returns the _old_ value — this is the polarity
 `wa-show`/`wa-hide` already had, and the opposite of what Lyra 7.x's own `lr-show`/`lr-hide` did on
 `lr-popover`/`lr-dropdown`. The `wa-*` → `lr-*` migration table treats the rename as mechanical, and
@@ -115,8 +120,8 @@ and easing. Under `prefers-reduced-motion: reduce`, registry timing flattens to
 frame and lifecycle remain intact. Passing `null` skips native interpolation but still emits the
 matching after-event before the method promise resolves. Because dialogs now animate on close too,
 `lr-after-hide` is normally deferred by roughly one animation. A removal while open emits
-`lr-hide`, `lr-dialog-close` (reason `'unmount'`) and `lr-after-hide` in that order, none of them
-cancelable, since the element is already gone.
+`lr-hide`, `lr-close` (reason `'unmount'`) and `lr-after-hide` in that
+order, none of them cancelable, since the element is already gone.
 
 **Stacking and the top layer:** an open dialog is promoted into the browser **top layer** (via
 `popover="manual"`), new in 8.0.0. That means it escapes every ancestor stacking context and every
@@ -205,7 +210,7 @@ Otherwise shared tokens include `--lr-space-l/-m/-s`, `--lr-color-surface/-borde
   dlg.addEventListener("lr-after-show", () =>
     console.log("enter animation done")
   );
-  dlg.addEventListener("lr-dialog-close", (e) =>
+  dlg.addEventListener("lr-close", (e) =>
     console.log("closed:", e.detail)
   );
   dlg.addEventListener("lr-after-hide", () =>
@@ -288,7 +293,7 @@ if (ok) deleteConversation();
 ```
 
 `confirm(options: ConfirmOptions): Promise<boolean>` where
-`ConfirmOptions = { title: string; description?: string; confirmLabel?: string /* = 'Confirm' */; cancelLabel?: string /* = 'Cancel' */; variant?: 'neutral' | 'danger' /* = 'neutral' */; tone?: 'neutral' | 'danger' /* @deprecated, use variant */ }`.
+`ConfirmOptions = { title: string; description?: string; confirmLabel?: string /* = 'Confirm' */; cancelLabel?: string /* = 'Cancel' */; variant?: 'neutral' | 'danger' /* = 'neutral' */ }`.
 
 Resolves `true` only when the confirm button is pressed — Escape, a backdrop click, and the cancel
 button all resolve `false`. It sets `lightDismiss = true` on its transient dialog explicitly, so the
@@ -299,8 +304,8 @@ of the call and removes it once settled, rather than reusing a persistent page-l
 stack, each tied to its own returned promise. `title` becomes a direct light-DOM `<h2>`, which per `<lr-dialog>`'s
 own heading-detection also drives the dialog's accessible name; `description`, if provided, becomes
 a direct light-DOM `<p>`. `variant: 'danger'` fills the confirm button with `--lr-color-danger`
-instead of `--lr-color-brand`, for destructive actions. The deprecated `tone` option is a one-major
-back-compat alias for `variant`; `variant` wins when both are set. Confirm/cancel actions deliberately use native
+instead of `--lr-color-brand`, for destructive actions. The deprecated `tone` option that preceded
+`variant` was removed in 10.0.0. Confirm/cancel actions deliberately use native
 inline-styled `<button>` elements so this helper does not register or import the broader button
 component; every color value is still a `--lr-*` token reference, never a raw literal. They carry the same interaction
 states as every other control in the library: a hover/pressed fill mixed toward
@@ -313,7 +318,7 @@ their `data-lr-confirm-action` attribute.
 **Known gotchas:**
 
 - Every dismissal path (confirm button, cancel button, Escape, backdrop click) funnels through
-  `<lr-dialog>`'s own `close()`/`lr-dialog-close` event, so there is exactly one place that
+  `<lr-dialog>`'s own `close()`/`lr-close` event, so there is exactly one place that
   resolves the promise and tears the dialog down — a consumer never needs to (and shouldn't) call
   `.remove()` itself. Because the close event is cancelable, `confirm()` waits through the full
   dispatch and remains pending/mounted when a listener calls `preventDefault()`.

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

@@ -112,19 +112,16 @@ being dragged. Plus shared tokens `--lr-color-surface`, `--lr-color-border`, `--
 
 ```html
 <div style="position: relative; block-size: 100vh;">
-  <lr-dock-panel
-    edge="end"
-    extent="320px"
-    min-extent="200px"
-    max-extent="480px"
-    collapsible
-    @lr-resize-input=${(e) => updateLayoutPreview(e.detail.extent)}
-    @lr-resize-change=${(e) => persistExtent(e.detail.extent)}
-    @lr-collapse-change=${(e) => console.log(e.detail.collapsed)}
-  >
+  <lr-dock-panel edge="end" extent="320px" min-extent="200px" max-extent="480px" collapsible>
     <div>Sidebar content — a chat thread list, an inspector, anything.</div>
   </lr-dock-panel>
 </div>
+<script type="module">
+  const panel = document.querySelector("lr-dock-panel");
+  panel.addEventListener("lr-resize-input", (e) => updateLayoutPreview(e.detail.extent));
+  panel.addEventListener("lr-resize-change", (e) => persistExtent(e.detail.extent));
+  panel.addEventListener("lr-collapse-change", (e) => console.log(e.detail.collapsed));
+</script>
 ```
 
 Pointer-drag-resize admits only a primary pointer using its primary button, then mirrors

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

@@ -154,11 +154,11 @@ entry) or a third-party PDF/office-doc viewer, but neither is a dependency of th
 
 ```html
 <lr-document-preview
+  id="text-preview"
   filename="board-notes.txt"
   mime-type="text/plain"
   src="/files/board-notes.txt"
   max-height="24rem"
-  @lr-render-error=${(e) => console.error(e.detail.error)}
 ></lr-document-preview>
 
 <!-- A host driving its own server-side conversion -->
@@ -168,6 +168,11 @@ entry) or a third-party PDF/office-doc viewer, but neither is a dependency of th
 <lr-document-preview filename="deck.pptx" mime-type="application/vnd.ms-powerpoint" src="/files/deck.pptx">
   <lr-code-block slot="unsupported" language="text">Open in PowerPoint to preview.</lr-code-block>
 </lr-document-preview>
+<script type="module">
+  document
+    .getElementById("text-preview")
+    .addEventListener("lr-render-error", (e) => console.error(e.detail.error));
+</script>
 ```
 
 Accessibility: after the initial silent baseline, entering `"converting"` without numeric

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

@@ -53,8 +53,9 @@ value, without suppressing the visible `name` heading.
 
 - `lr-close` — `detail: DocumentViewerCloseReason`, the viewer shell dialog's dismissal reason.
   The event is emitted after the viewer sets `open` to `false`. A registered renderer may compose
-  its own descendant dialog; closing that inner dialog keeps its normal `lr-dialog-close` path and
-  does not close the document viewer.
+  its own descendant dialog; closing that inner dialog keeps its own `lr-close` path — the shell
+  guards on `event.target !== event.currentTarget` — and does not close the document viewer.
+  (`<lr-dialog>`'s close event was spelled `lr-dialog-close` before 10.0.0.)
 - `lr-download` — `detail: { src, filename }`, emitted when the native safe download action is
   activated. The browser download itself is handled by the link.
 - `lr-anchor-result` — `detail: { found }`. Emitted by this shell as `{ found: false }` once per

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

@@ -7,7 +7,7 @@
 - **Family** `components/charts/` — see `llms/index.md` for its siblings
 - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md`
 - **Deprecations** none
-- **Optional peers** `chart.js`, `chartjs-plugin-datalabels`, `chartjs-plugin-zoom` — see `llms/peers.md`
+- **Optional peers** `chart.js`, `chartjs-plugin-annotation`, `chartjs-plugin-datalabels`, `chartjs-plugin-zoom` — see `llms/peers.md`
 - **Themeable via** 15 parts, 33 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`
@@ -25,7 +25,8 @@ and behavior there. **See `llms/components/lr-chart.md` for the details, code ex
 of every entry in these lists.**
 
 **Properties:** `description`, `grid`, `indexAxis` (`index-axis`), `label`, `hiddenDatasets`, `legendPosition`
-(`legend-position`), `max`, `min`, `plugins`, `stacked`, `withoutAnimation` (`without-animation`),
+(`legend-position`), `max`, `min`, `plugins`, `scaleType` (`scale-type`), `annotations`,
+`stacked`, `withoutAnimation` (`without-animation`),
 `withoutLegend` (`without-legend`), `withoutTooltip` (`without-tooltip`), `xLabel` (`x-label`),
 `yLabel` (`y-label`), plus additive `labels`, `datasets`, `valueFormatter`, `formatter`, `area`, `zoom`,
 `height`, `y2Label` (`y2-label`), `beginAtZero` (`begin-at-zero`), `dataLabels`
@@ -66,7 +67,7 @@ together. The mirrored hooks are `--border-color-1`,
 `zoom` is set, and `chartjs-plugin-datalabels` only once `data-labels`/`stack-totals` is set.
 
 ```html
-<lr-bar-chart legend></lr-bar-chart>
+<lr-bar-chart></lr-bar-chart>
 <lr-pie-chart></lr-pie-chart>
 <script>
   document.querySelector('lr-bar-chart').labels = ['A', 'B'];

package/llms/components/lr-drawer.md

@@ -19,7 +19,7 @@ A modal panel anchored to one logical edge of the viewport. `LyraDrawer` extends
 inherits the entire dialog contract unchanged: focus trapping, Escape and opt-in backdrop dismissal,
 document scroll locking, browser **top-layer** promotion, overlay stacking, accessible naming, the
 `show()`/`hide()`/`close()` methods and the whole
-`lr-show`/`lr-after-show`/`lr-hide`/`lr-after-hide`/`lr-dialog-close` lifecycle. `contained` switches
+`lr-show`/`lr-after-show`/`lr-hide`/`lr-after-hide`/`lr-close` lifecycle. `contained` switches
 to an absolute, nonmodal panel inside the nearest containing block; only that mode, `placement`, and
 the slide animation are its own.
 
@@ -50,8 +50,8 @@ the slide animation are its own.
 promise settles after the matching `lr-after-*` event.
 
 **Events:** `lr-show` (cancelable), `lr-after-show`, `lr-hide` (cancelable), `lr-after-hide`, and
-`lr-initial-focus` (cancelable), `lr-request-close` (cancelable, detail source), and
-`lr-dialog-close` (`detail: DialogCloseReason`, cancelable) — all inherited unchanged from
+`lr-initial-focus` (cancelable), `lr-request-close` (cancelable, detail source), and `lr-close`
+(`detail: DialogCloseReason`, cancelable) — all inherited unchanged from
 `lr-dialog`; see that section for details and veto rules. `lr-after-show` /
 `lr-after-hide` fire once the slide animation has finished, so they are deferred by roughly one
 animation compared with the state flip.

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

@@ -17,7 +17,7 @@
 
 A dossier card for one knowledge-graph entity: type badge, description, key/value property rows,
 degree, community chip, plus a built-in "focus in graph" action. Never fetches or focuses a graph
-itself — `lr-entity-activate` is a request a host routes into `lr-graph`'s own
+itself — `lr-entity-select` is a request a host routes into `lr-graph`'s own
 `focusNode(id, options?)`.
 
 **Properties:**
@@ -42,7 +42,7 @@ number; communityId?: string }`; field names deliberately mirror `lr-graph`'s `L
   set — there is nothing left to tighten. The exported alias `EntityCardAppearance` is retained as a
   name for the same union.
 
-**Events:** `lr-entity-activate` (`detail: { entityId }`, the built-in focus button was activated).
+**Events:** `lr-entity-select` (`detail: { entityId }`, the built-in focus button was activated).
 
 **Slots:** default (extra body content below the property rows, e.g. a `lr-neighbor-list`),
 `actions` (extra header actions alongside the built-in focus button).
@@ -75,7 +75,7 @@ from tokens.
   };
   document
     .getElementById("card")
-    .addEventListener("lr-entity-activate", (e) =>
+    .addEventListener("lr-entity-select", (e) =>
       graph.focusNode(e.detail.entityId)
     );
 </script>

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

@@ -33,7 +33,7 @@ before the type template is composed, so it never produces a leading punctuation
 `, person`. An authored host `aria-label` intentionally names only the custom-element boundary;
 it is not copied onto the shadow button because host naming does not cross that boundary.
 
-**Events:** `lr-entity-activate` (`detail: { entityId }`, click, or Enter while focused),
+**Events:** `lr-entity-select` (`detail: { entityId }`, click, or Enter while focused),
 `lr-entity-open` (`detail: { entityId }`, dblclick, or Space while focused).
 
 **Slots:** default — rich preview content (typically a compact `lr-entity-card`), shown in a

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

@@ -53,7 +53,10 @@ shape?: 'circle' | 'square' | 'diamond' }`, the `lr-graph.nodeTypes` entry shape
   `aria-label` names the dossier as a whole and is not cloned onto the strip
 
 **Events:** declares none of its own. Every composed child's event bubbles through unmodified
-(`composed: true`): `lr-entity-activate` (`detail: { entityId, occurrenceIndex? }`), `lr-node-expand` (`detail: { nodeId }`),
+(`composed: true`): `lr-entity-select` (`detail: { entityId }`, surfaced from the embedded entity
+card or neighbor list), `lr-entity-activate` (`detail: { entityId, occurrenceIndex? }` — surfaced
+from the embedded provenance panel's own community card or relationship path strip, the only
+source carrying `occurrenceIndex`), `lr-node-expand` (`detail: { nodeId }`),
 `lr-chunk-open` (`detail: { chunkId, sourceId, anchor? }`), `lr-expand` (`detail: { chunkId, expanded }`),
 `lr-toggle` (`detail: { section, expanded }`), and `lr-tab-show`
 (`detail: { tabId: LyraEntityDossierTab }`, where `LyraEntityDossierTab = 'relationships' | 'chunks'

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

@@ -6,8 +6,8 @@
 - **Class** `LyraFileInput`, also available unregistered from `@aceshooting/lyra-ui/components/media/file-input/file-input.class.js`
 - **Family** `components/media/` — see `llms/index.md` for its siblings
 - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md`
-- **Deprecated part** `base` since `8.2.3`; use part `::part(file-input)`; removal not before `10.0.0` — The file-input part names the interactive picker surface; base remains on that same node during the compatibility window.
-- **Deprecated part** `label` since `8.2.3`; use part `::part(form-control-label)`; removal not before `10.0.0` — The form-control-label part follows the shared form-control vocabulary; label remains on that same node during the compatibility window.
+- **Deprecated part** `base` since `8.2.3`; use part `::part(file-input)`; removal not before `10.0.0` — The file-input part names the interactive picker surface; base remains on that same node during the compatibility window. That version is a policy floor, not a plan: `wa-file-input` still publishes its own deprecated `base` part, so this alias is removed only when upstream's is.
+- **Deprecated part** `label` since `8.2.3`; use part `::part(form-control-label)`; removal not before `10.0.0` — The form-control-label part follows the shared form-control vocabulary; label remains on that same node during the compatibility window. That version is a policy floor, not a plan: `wa-file-input` still publishes its own deprecated `label` part, so this alias is removed only when upstream's is.
 - **Optional peers** none
 - **Themeable via** 22 parts, 17 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`

package/llms/components/lr-flag.md

@@ -8,7 +8,7 @@
 - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md`
 - **Deprecations** none
 - **Optional peers** `@aceshooting/lyra-flags` — see `llms/peers.md`
-- **Themeable via** 2 parts, 3 custom properties — see this component's own `@csspart`/`@cssprop` list below
+- **Themeable via** 3 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,7 +20,16 @@ Country/language flag image. Flag artwork ships in a **separate, optional peer p
 
 **Properties:**
 
-- `country?: string` (ISO 3166-1 alpha-2, e.g. `"fr"` — takes precedence over `language`)
+- `country?: string` (ISO 3166-1 **alpha-2 or alpha-3**, e.g. `"fr"` or `"FRA"` — takes
+  precedence over `language`). Length alone disambiguates the two code spaces, so no format hint
+  is needed: a 2-letter value is alpha-2, a 3-letter value is alpha-3. Alpha-3 support exists
+  because public statistical sources (World Bank, UN, IMF, most open-data portals) key country
+  records on alpha-3; the 249 officially-assigned mappings are packed as a ~1.2 KB fixed-width
+  string and expanded lazily on the first alpha-3 lookup, so an alpha-2-only app never pays for
+  them. Withdrawn and user-assigned codes deliberately do not map to a successor state — they
+  take the unresolved path below
+- `fallback?: string` — placeholder image URL rendered when the code cannot resolve to a current
+  flag. The `fallback` slot wins over it
 - `language?: string` (BCP-47-ish tag, e.g. `"en"`/`"en-US"`, resolved to a representative country
   via `languageToCountry()`)
 - `src?: string` (a pre-resolved flag image URL — takes precedence over `country`/`language` and
@@ -45,11 +54,17 @@ authoring types are `LyraFlagShape`, `LyraFlagFidelity`, and `LyraFlagUrlResolve
 
 **Events:** none.
 
-**Slots:** none.
+**Slots:** `fallback` — rendered in place of the flag when `country`/`language` cannot resolve to a
+current flag (an unassigned, historical, or malformed code). Wins over the `fallback` property.
 
-**CSS parts:** `image` (the underlying `<img>`, exposed once native loading succeeds), `error`
+**CSS parts:** `image` (the underlying `<img>`, exposed once native loading succeeds),
+`fallback-image` (the `fallback` property's placeholder, when no slot content is supplied), `error`
 (contained localized visible text rendered when URL validation, peer resolution, or native image
-loading fails). The host reflects the terminal error state with `data-error`.
+loading fails). The host reflects the terminal error state with `data-error`, and an unresolvable
+code with `data-unresolved`. **The two are deliberately distinct:** a dissolved federation or
+unrecognized territory in a longitudinal dataset is *data*, not a defect, so it renders the neutral
+fallback (occupying its normal footprint in a table or card grid) rather than localized error
+wording that reads to a user as a bug. Style the two states apart with those attributes.
 
 **Themeable custom properties:** `--lr-flag-radius` (default `calc(var(--lr-radius) * 0.33)` —
 rectangular corner radius), `--lr-flag-aspect-ratio` (default `4 / 3`), and

package/llms/components/lr-heatmap.md

@@ -69,6 +69,17 @@ weekdayLabelText?: (jsWeekday:number)=>string|undefined; monthLabelText?:
   measured `clientWidth` on every draw/resize instead of the fixed `cell-size`, so the grid actually
   fills the available width; now applies to calendar mode as well as matrix mode — see gotchas for
   the default, non-`fit-to-width` behavior)
+- `rowLabelWidth?: number | 'auto'` (attribute `row-label-width`, reflected) — width, in CSS px, of
+  the **matrix** row-label gutter, or `'auto'` to measure the widest label and size the gutter to
+  fit (never below the built-in `60`, never above 40% of the host width, so one long label cannot
+  squeeze out the cells it describes). Unset keeps the built-in `60`, so no existing chart reflows.
+  Independently of this, a label too wide for the resolved gutter is truncated with an ellipsis
+  rather than clipped mid-glyph — clipping read as a rendering fault, truncation reads as "there is
+  more here". `cellText` still carries the full label to the tooltip and the keyboard announcement.
+  A malformed value is ignored rather than collapsing the gutter. Calendar mode is unaffected; it
+  has its own fixed weekday gutter
+- `colLabelHeight?: number` (attribute `col-label-height`) — height, in CSS px, of the matrix
+  column-label band. Unset keeps the built-in `20`
 - `maxCellSize?: number` (attribute `max-cell-size`) — ceiling, in CSS px, on the cell size
   `fitToWidth` derives from the host width, in **both** modes. Exists because `fitToWidth` divides
   the _whole_ host width across the grid, so a 5-week calendar or a 3-column matrix in a wide pane
@@ -86,6 +97,23 @@ weekdayLabelText?: (jsWeekday:number)=>string|undefined; monthLabelText?:
   color ramp via `sqrtStep()` instead of mapping linearly; in calendar mode, the default `'linear'`
   still buckets by quartile (`quartileBucket()`, unchanged), while `'sqrt'` instead compresses via the
   same `sqrtStep()` magnitude compression as matrix mode, so one heavy day doesn't wash out the rest
+- `domain?: [number, number]` (attribute: false) — pins the color ramp's input domain instead of
+  deriving it from the data's own extremes, so two heatmaps of comparable data can share a scale
+  rather than each normalizing to its own min/max. A reversed pair is normalized; a degenerate or
+  non-finite one falls back to the derived range
+- `midpoint?: number` — anchors a diverging ramp's neutral color on this value rather than at the
+  middle of the domain, scaling the two halves independently (`lo`→0, `midpoint`→0.5, `hi`→1). A
+  midpoint outside the resolved domain degrades to plain normalization rather than distorting the
+  ramp
+- **Signed data.** Setting either `domain` or `midpoint` opts the component into signed data, where
+  only a **non-finite** value is no-data. With neither set (the default), a negative value is
+  no-data — matching the long-documented `-1` sentinel, since a matrix of counts has no meaningful
+  negative. Declaring a domain or midpoint is what disambiguates "a real negative" from "the
+  sentinel", so signed datasets render their negative half instead of dropping it. In signed mode a
+  structurally absent matrix cell reads as `NaN` so it stays no-data while a real `-1` beside it
+  renders on the ramp; in default mode an absent cell still resolves to `-1`, keeping `valueAt()`
+  and the `lr-cell-click` payload unchanged. `scale="sqrt"` rejects negatives in both modes — a
+  square root of a negative has no meaning
 - `bucketCount: number = 5` (attribute `bucket-count` — calendar mode only; non-finite values fall
   back to 5, while finite values are floored and clamped to 2–256 before the color-ramp allocation)
 - `annotations: readonly HeatmapAnnotation[] = []` (attribute: false) — `HeatmapAnnotation { row?: number;

package/llms/components/lr-histogram.md

@@ -7,7 +7,7 @@
 - **Family** `components/charts/` — see `llms/index.md` for its siblings
 - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md`
 - **Deprecations** none
-- **Optional peers** `chart.js`, `chartjs-plugin-datalabels`, `chartjs-plugin-zoom` — see `llms/peers.md`
+- **Optional peers** `chart.js`, `chartjs-plugin-annotation`, `chartjs-plugin-datalabels`, `chartjs-plugin-zoom` — see `llms/peers.md`
 - **Themeable via** 15 parts, 33 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`
 
@@ -25,6 +25,8 @@ Bins `values` into `bins` equal-width buckets and renders as a bar chart (extend
 - `seriesLabel: string = ''` (attribute `series-label`) — dataset label used for the
   legend/tooltip/table; empty falls back to localized "Frequency". Inherited `label` keeps its
   chart-wide accessible-name meaning.
+- inherits `lr-chart`'s full surface, including `scaleType` (`scale-type`) and `annotations` —
+  a logarithmic frequency axis and threshold/band markers both apply to a histogram
 - `labels`/`datasets`/`type` are **derived, read-only** (installed as getter/setter pairs on the
   prototype; direct writes are silently ignored) — `labels`/`datasets` are computed from
   `values`/`bins` (memoized per instance, keyed by reference equality on `values` plus the

package/llms/components/lr-icon.md

@@ -6,7 +6,7 @@
 - **Class** `LyraIcon`, also available unregistered from `@aceshooting/lyra-ui/components/utility/icon/icon.class.js`
 - **Family** `components/utility/` — see `llms/index.md` for its siblings
 - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md`
-- **Deprecated property** `autoWidth` / `auto-width` since `8.0.0`; use property `canvas="auto"`; removal not before `10.0.0` — autoWidth is a boolean compatibility spelling that cannot express fixed canvas sizes; canvas covers both automatic and explicit sizing.
+- **Deprecated property** `autoWidth` / `auto-width` since `8.0.0`; use property `canvas="auto"`; removal not before `10.0.0` — autoWidth is a boolean compatibility spelling that cannot express fixed canvas sizes; canvas covers both automatic and explicit sizing. That version is a policy floor, not a plan: `wa-icon` still publishes its own deprecated `auto-width` attribute, so this alias is removed only when upstream's is.
 - **Optional peers** `dompurify` — see `llms/peers.md`
 - **Themeable via** 4 parts, 45 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`

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

@@ -21,7 +21,8 @@ It intentionally does not fetch remote references or validate values.
 
 **Properties:** clone-owned, bounded, frozen `schema: JsonSchemaNode | null = null` and
 `issues: readonly SchemaValidationIssue[] = []` (attribute: false); reassign a new schema record or
-issue array after changes. `selectedPath: string = ''` (attribute `selected-path`);
+issue array after changes. `selectedPath: string | null = null` (attribute `selected-path`) —
+`null` means no selection, while the empty string is the valid JSON Pointer for the schema root;
 `maxDepth: number = 20` (attribute `max-depth`, clamped to 100); `label: string = ''`.
 
 **Exported types:** `JsonSchemaNode` covers `$ref`, type/title/description, properties/items,

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

@@ -79,9 +79,14 @@ same self-toggle-then-emit contract `lr-graph-legend` uses, so every feature wor
 - `lr-hidden-types-change` (`detail: { hiddenTypes: string[] }`) — a node type's visibility changed
   via the composed legend. Follows the same self-toggle-then-emit contract as `lr-pin-change`/
   `lr-search-change`, so reassigning back is optional.
-- `lr-search-change` (`detail: { searchQuery: string }`) — the user typed in the toolbar's search
-  box. Already self-applied before emitting, so reassigning back is optional; a direct host
-  assignment to `searchQuery` stays silent.
+- `lr-search-change` (`detail: { query: string; matchCount: number; matchCountExact: boolean }`) —
+  the user typed in the toolbar's search box. `query` is the canonical `LyraSearchChangeDetail`
+  field name. `matchCount` is the same live node-filter total the result list and its live-region
+  announcement already compute (`0` while the query is empty). `matchCountExact` is always `true` —
+  this component's node filter has no truncating ceiling, unlike a paginated text-search viewer.
+  There is no `activeIndex`: this is a live node filter, not a cursor-based search. The component
+  has already applied the query to its own `searchQuery` property before emitting, so reassigning
+  it back is optional and a direct host assignment stays silent.
 - Bubbling straight through from composed children, unmodified: `lr-node-click`
   (`detail: { nodeId, x, y }`), `lr-link-click` (`detail: { sourceNodeId, targetNodeId, linkId? }`), `lr-community-click`
   (`detail: { communityId }`), `lr-node-expand` (`detail: { nodeId }`, from `lr-graph` and/or `lr-neighbor-list`),

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

@@ -6,7 +6,7 @@
 - **Class** `LyraKnownDate`, also available unregistered from `@aceshooting/lyra-ui/components/utility/known-date/known-date.class.js`
 - **Family** `components/utility/` — see `llms/index.md` for its siblings
 - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md`
-- **Deprecated part** `label` since `8.0.0`; use part `::part(form-control-label)`; removal not before `10.0.0` — The form-control-label part matches the shared form-control vocabulary; label remains on that same node during the compatibility window.
+- **Deprecated part** `label` since `8.0.0`; use part `::part(form-control-label)`; removal not before `10.0.0` — The form-control-label part matches the shared form-control vocabulary; label remains on that same node during the compatibility window. That version is a policy floor, not a plan: `wa-known-date` still publishes its own deprecated `label` part, so this alias is removed only when upstream's is.
 - **Optional peers** none
 - **Themeable via** 17 parts, 13 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`
@@ -119,7 +119,9 @@ assigned nodes update the announcement without requiring the wrapper component t
 
 The `label` part alias was deprecated in 8.0.0 in favor of the shared form vocabulary
 `form-control-label`. Both names remain on the same node during the compatibility window; use
-`::part(form-control-label)` in new CSS. The alias will not be removed before 10.0.0.
+`::part(form-control-label)` in new CSS. Removal is not scheduled: Web Awesome still publishes its
+own deprecated `label` part on `<wa-known-date>`, and a mirrored tag owes its whole upstream
+surface, so the alias goes only when upstream's does.
 
 **The required marker.** The `*` the legend grows while `required` is the library's shared
 required-field marker, and it takes the same three consumer-settable properties every other

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

@@ -7,7 +7,7 @@
 - **Family** `components/charts/` — see `llms/index.md` for its siblings
 - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md`
 - **Deprecations** none
-- **Optional peers** `chart.js`, `chartjs-plugin-datalabels`, `chartjs-plugin-zoom` — see `llms/peers.md`
+- **Optional peers** `chart.js`, `chartjs-plugin-annotation`, `chartjs-plugin-datalabels`, `chartjs-plugin-zoom` — see `llms/peers.md`
 - **Themeable via** 15 parts, 33 custom properties — see this component's own `@csspart`/`@cssprop` list below
 - **Documented with** `lr-bar-chart`, `lr-pie-chart`, `lr-doughnut-chart`, `lr-radar-chart`, `lr-polar-area-chart`, `lr-bubble-chart`, `lr-scatter-chart` (same section below)
 - **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
@@ -25,7 +25,8 @@ and behavior there. **See `llms/components/lr-chart.md` for the details, code ex
 of every entry in these lists.**
 
 **Properties:** `description`, `grid`, `indexAxis` (`index-axis`), `label`, `hiddenDatasets`, `legendPosition`
-(`legend-position`), `max`, `min`, `plugins`, `stacked`, `withoutAnimation` (`without-animation`),
+(`legend-position`), `max`, `min`, `plugins`, `scaleType` (`scale-type`), `annotations`,
+`stacked`, `withoutAnimation` (`without-animation`),
 `withoutLegend` (`without-legend`), `withoutTooltip` (`without-tooltip`), `xLabel` (`x-label`),
 `yLabel` (`y-label`), plus additive `labels`, `datasets`, `valueFormatter`, `formatter`, `area`, `zoom`,
 `height`, `y2Label` (`y2-label`), `beginAtZero` (`begin-at-zero`), `dataLabels`
@@ -66,7 +67,7 @@ together. The mirrored hooks are `--border-color-1`,
 `zoom` is set, and `chartjs-plugin-datalabels` only once `data-labels`/`stack-totals` is set.
 
 ```html
-<lr-bar-chart legend></lr-bar-chart>
+<lr-bar-chart></lr-bar-chart>
 <lr-pie-chart></lr-pie-chart>
 <script>
   document.querySelector('lr-bar-chart').labels = ['A', 'B'];

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

@@ -7,7 +7,7 @@
 - **Family** `components/charts/` — see `llms/index.md` for its siblings
 - **Status** `stable` since `4.0.0` — see the maturity and deprecation policy in `llms/shared.md`
 - **Deprecations** none
-- **Optional peers** `chart.js`, `chartjs-plugin-datalabels`, `chartjs-plugin-zoom` — see `llms/peers.md`
+- **Optional peers** `chart.js`, `chartjs-plugin-annotation`, `chartjs-plugin-datalabels`, `chartjs-plugin-zoom` — see `llms/peers.md`
 - **Themeable via** 17 parts, 16 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`
 
@@ -103,11 +103,21 @@ passthrough). Not a subclass of `LyraChart`.
 - `valueAxisGutter?: number` (attribute `value-axis-gutter`) — value-axis gutter width.
 - `barGapRatio?: number` (attribute `bar-gap-ratio`) — overrides the internal 0.2 `BAR_GROUP_GAP`
   fraction of a category slot left as a gap between categories. Unset keeps the fixed 0.2.
-- `scale: 'linear' | 'sqrt' = 'linear'` (bar type only) — `'sqrt'` maps a bar's value to height via
-  `Math.sqrt(value / domainMax)` instead of the standard linear `niceDomain` fraction (mirroring
-  `lr-heatmap`'s matrix-mode `sqrt` scale), so a skewed dataset's smaller bars aren't washed out
-  by one dominant value; gridlines/tick labels stay on the linear domain either way, and `type="line"`
-  ignores it entirely.
+- `scale: 'linear' | 'sqrt' | 'logarithmic' = 'linear'` — `'sqrt'` (**bar type only**) maps a bar's
+  value to height via `Math.sqrt(value / domainMax)` instead of the standard linear `niceDomain`
+  fraction (mirroring `lr-heatmap`'s matrix-mode `sqrt` scale), so a skewed dataset's smaller bars
+  aren't washed out by one dominant value; under `'sqrt'` gridlines/tick labels stay on the linear
+  domain and `type="line"` ignores it entirely.
+  `'logarithmic'` is the base-10 value axis for data spanning several orders of magnitude, where a
+  linear axis collapses everything below the maximum into the baseline. Unlike `'sqrt'` it applies
+  to **bars, line points and gridlines alike**, since a log axis whose gridlines stayed linear
+  would misrepresent the plot. Its lower bound is the smallest *positive* datum rather than the
+  linear `lo`: `beginAtZero` defaults to true, so `lo` is normally `0`, which has no logarithm —
+  deriving the floor from the data is what makes a 1…1000 series span three even decades instead of
+  collapsing onto one. Values at or below that floor (including zero and negatives, which have no
+  real logarithm) pin to the axis floor rather than producing `-Infinity` geometry, and a degenerate
+  domain falls back to the linear fraction. `lr-chart`'s own `scaleType` is the Chart.js-backed
+  equivalent for the full charts.
 - `withoutValueAxis: boolean = false` (attribute `without-value-axis`) — suppresses gridlines and
   value-axis tick labels; x-axis category labels remain.
 - `selectedIndices: readonly number[] = []` (attribute: false) — applies to every interactive data mark for