@aceshooting/lyra-ui 9.1.0 → 10.0.1

package/llms-full.txt

@@ -1145,6 +1145,70 @@ canvas consumer's redraw to its normal microtask/render schedule. The optional r
 browser realm; it does not limit invalidation to a subtree. The function is a no-op during server
 rendering and retains no document or stylesheet after the last canvas consumer disconnects.
 
+## Preventing layout shift from lazy-upgrading elements (CLS)
+
+An undefined custom element is an inline box with no intrinsic size, so every `lr-*` in the initial
+viewport contributes a reflow as its definition loads. Components that additionally defer on an
+optional peer (`lr-chart`, `lr-map`, `lr-flag`, `lr-flow-canvas`, `lr-knowledge-graph-explorer`)
+render a skeleton while that peer resolves, which can cost a second shift when the real content
+replaces it. Each component is individually well-behaved; the aggregate on a first paint is what
+costs a Lighthouse Cumulative Layout Shift score.
+
+Lyra ships an optional, opt-in stylesheet that reserves each component's intrinsic footprint before
+upgrade:
+
+```css
+@import "@aceshooting/lyra-ui/reservations.css";
+```
+
+It styles **only** `:not(:defined)` elements, inside an `@layer lr-reservations`, so it becomes inert
+the moment a definition upgrades and can never fight a component's own layout. It sets no colors and
+no `:root` rules.
+
+**Every reservation is expressed with the same custom property and fallback token the component's
+own stylesheet uses** — `--lr-chart-height` / `--lr-size-280px` for the chart family,
+`--lr-flag-aspect-ratio` for `lr-flag`, `--lr-form-control-height` for the field controls, and so
+on. That is the point of shipping it rather than documenting measured pixel values: a hand-written
+reservation rots silently the moment a component's default changes, whereas these track it, and
+theming a component through its documented custom property re-themes its reservation with it.
+
+Hand-rolling equivalent rules is still fine — the pattern is just:
+
+```css
+lr-chart:not(:defined) {
+  display: block;
+  min-block-size: var(--lr-chart-height, var(--lr-size-280px));
+}
+```
+
+Two things worth knowing:
+
+- A per-instance override needs the matching custom property to be set as well, not only the
+  attribute, or the pre-upgrade frame and the upgraded frame will disagree. `<lr-chart height="500px">`
+  should carry `style="--lr-chart-height: 500px"` too if it sits above the fold.
+- The reservation covers the definition-upgrade shift. A component that then swaps a skeleton for
+  peer-resolved content stays stable as long as the reserved box matches the final footprint, which
+  is why the reservations target each component's *final* default size rather than its skeleton's.
+
+## Scope: what this library does not provide
+
+Lyra is a component library, not an application framework. The following are deliberately out of
+scope, so they are worth not searching the catalog for:
+
+- **Client-side routing.** There is no router and no route-outlet component. URL ownership belongs to
+  the application (or its router of choice), because a component library that took it over would
+  conflict with every framework router a consumer might already run. The navigation components are
+  designed to be *driven* by whatever router you use rather than to own the URL themselves:
+  `lr-app-rail-item`, `lr-breadcrumb-item` and `lr-tab-group` all expose their active/selected state
+  as ordinary reflected properties, so binding is a one-way write from your route state plus a click
+  handler that calls your router. Wire it once in your shell component; there is no Lyra-specific
+  pattern to learn.
+- **Data fetching, caching, and state management.** Components take data as properties and emit
+  events; they never fetch on your behalf, except the documented viewers/`src`-taking components,
+  which are explicit about it.
+- **Form submission and validation orchestration.** Form-associated controls integrate with the
+  native `<form>`/`ElementInternals` contract; the submission lifecycle stays the application's.
+
 ## Optional native styles and CSS utilities
 
 Lyra ships two independent light-DOM stylesheets. Neither is imported by the root barrel, a family
@@ -1259,7 +1323,10 @@ setLyraLocale("fr"); // page-level selection; see the precedence order below
 ```
 
 ```html
-<lr-toast .strings=${{ close: 'Fermer' }}></lr-toast>
+<lr-toast></lr-toast>
+<script type="module">
+  document.querySelector("lr-toast").strings = { close: "Fermer" };
+</script>
 ```
 
 **Which locale a component ends up using.** Four sources, first answer wins:
@@ -1651,7 +1718,7 @@ control) is a single tab stop using a roving `tabindex`; arrow keys move within
 `Escape` dismisses the topmost dismissible overlay and returns focus to whatever opened it.
 `ArrowLeft`/`ArrowRight` mean previous/next and swap under `dir="rtl"`.
 
-**What that contract is verified by, precisely.** Every one of the 283 components carries at least
+**What that contract is verified by, precisely.** Every one of the 284 public tags carries at least
 one axe-core assertion in its own directory's tests, in a test that mounts its own tag; contrast
 (4.5:1 text, 3:1 control borders, in both the light and dark palettes), a 40px minimum target size,
 pressed-state coverage for every hoverable part, and `::part()` reachability are separate blocking
@@ -1672,6 +1739,19 @@ files matter when scaffolding a project's editor configuration. Build tools can
 through the explicit `@aceshooting/lyra-ui/custom-elements.json` package export; native Node ESM
 uses `with { type: 'json' }` on that import.
 
+**Inherited members in `custom-elements.json`.** A subclass declaration's `cssParts` array is
+always the complete flattened set, including everything inherited from a superclass — `::part()`
+has no type-level inheritance chain a consumer could otherwise walk. `attributes`, `members`,
+`events`, `slots`, and `cssProperties` are the opposite: a subclass declaration lists only its own
+entries plus any inherited entry it explicitly overrides, pruning an inherited-and-unmodified entry
+of those four kinds. This is intentional, not a gap — a TypeScript/JS consumer already gets the
+full set for free from the generated `.d.ts` `extends` chain, the same resolution `web-types.json`
+and `vscode-html-data.json` perform ahead of time. A consumer reading `custom-elements.json`
+directly and needing the complete `attributes`/`members`/`events`/`slots`/`cssProperties` set for
+those four kinds must walk the declaration's own `superclass.name`/`superclass.module` across
+`modules[].declarations[]` itself, or read `web-types.json`/`vscode-html-data.json` instead, which
+are already fully resolved.
+
 ## Independence and migration
 
 Lyra has no runtime, theme, or design-token dependency on Shoelace or Web Awesome. Documented `wa-*`
@@ -2844,6 +2924,7 @@ These named interfaces and helper signatures are available to typed integrations
 
 - **`internal-canvas-color-contracts`** — Shared utility contracts.
   `resolveCanvasColor(/* public names: scope, color, fallback */): unknown`
+  `resolveCanvasColors(/* public names: scope, colors, fallback */): unknown`
 
 - **`internal-localization-runtime-contracts`** — Shared utility contracts.
   `getLyraLocaleDirection(/* public names: locale */): unknown`
@@ -3829,6 +3910,32 @@ These named interfaces and helper signatures are available to typed integrations
 
 # Form controls & inputs (`components/forms/`)
 
+## Breaking changes in 10.0.0
+
+`<lr-swatch-picker>` drops the three members it carried through 9.x as documented one-major
+back-compat aliases, each with a like-for-like replacement that has shipped since. The `options`
+property is now `items` — same frozen owned-snapshot contract, still `attribute: false`, so no
+markup changes. The `label` property/attribute is now `accessibleLabel` (attribute `aria-label`), or
+the host `aria-label` directly; this is the one worth grepping for, because an un-updated
+`<lr-swatch-picker label="Brand colours">` leaves the internal `role="radiogroup"` with no accessible
+name at all rather than failing loudly. And the exported `SwatchOption` type is now
+`SwatchPickerItem`. The item shape itself is unchanged, including its own per-item `label` field,
+which is a different member and stays.
+
+Also corrected in 10.0.0 — not breaking, but visible. A specificity sweep found rules that were
+meant to win yet were losing to another rule in the same shadow stylesheet, so their declarations
+never applied at all. In this family: arrow-keying onto the already-selected option in
+`<lr-select>` or `<lr-combobox>` produces a visible keyboard highlight again — `[aria-selected="true"]`
+was written after the active-descendant rule at equal specificity and swallowed it, so the highlight
+was absent exactly on the row a user is most likely to arrow onto first. `appearance="filled"` has a
+focus indicator again on `<lr-combobox>` and `<lr-date-input>`, both of which previously had none:
+the appearance rule out-ranked `:focus-within`, and the only `outline` in the focus rule was
+`solid transparent`. Both now express appearance as private custom properties, so no `[part]` rule
+can out-rank another. `<lr-option>` and `<lr-time-range>`'s active preset regain their pointer
+feedback, and `<lr-token-input>` can now veto all three of its mutations (`lr-add` and
+`lr-token-edit` became cancelable alongside `lr-remove`, which already was — additive; see that
+section).
+
 ## Setter-only `null` clearing in 8.0.0
 
 Several mapped string IDLs accept `null` on assignment without widening their read type. This is a
@@ -4247,7 +4354,10 @@ box visibly (nothing is clipped or made unreachable), so leave it unset there.
 plain-text contract even when a separate WA `label` override is present.
 
 **Events:** `lr-option-change` — bubbles when the option's label or selectable data changes so
-its parent `lr-combobox` or `lr-select` can refresh its normalized option rows.
+its parent `lr-combobox` or `lr-select` can refresh its normalized option rows. It is a private
+child-to-parent refresh signal, not a picker event: the owning `lr-combobox`/`lr-select` consumes
+it and stops it, so it never reaches a listener on the picker host (whose own contract is
+`lr-change`/`lr-input`/`change`/`input`). Listen on the `<lr-option>` itself to observe it.
 
 **Slots:** default (visible label), `start`/`end` (WA adornments), and `prefix`/`suffix` (Shoelace
 aliases). `start` and `prefix` project into one leading wrapper; `end` and `suffix` project into one
@@ -4343,7 +4453,7 @@ synchronous and fires no `input`/`change`/`lr-change` event.
 
 **Additional API surface:**
 
-- `part="tag-label"` — The wrapping/ellipsis-safe selected-tag label.
+- `part="tag-label"` — The selected-tag label. Kept on one line and truncated with an ellipsis at `--tag-max-size` (default `var(--lr-size-5rem)`), rather than wrapped. Note that `lr-select`'s tag of the same name defaults to `var(--lr-size-12rem)`, so the same `--tag-max-size` value yields a wider tag there.
 
 ---
 
@@ -6184,7 +6294,12 @@ than adding outer padding around the buttons.
 - `value: string` (also accepts a `Date` or `null` when assigned) — strict `HH:mm`, optional
   `:ss`/`.sss`; `Date` reads local clock fields without timezone conversion. Invalid strings and
   `null` normalize to `''`. `valueAsNumber` is milliseconds since midnight (`NaN` while blank),
-  and `valueAsDate` applies the clock fields to today's local date (`null` while blank).
+  and `valueAsDate` applies the clock fields to today's local date (`null` while blank). Both are
+  settable, like the native `<input type="time">` properties they mirror: assigning `valueAsNumber`
+  sets `value` from the same scale, and out-of-range or non-finite figures clear the field rather
+  than wrapping into a different time; assigning `valueAsDate` reads the same local clock fields
+  back off the Date, so it round-trips with the getter, and `null`/an invalid Date clears. Both
+  assignments are silent, again like the native properties.
 - `defaultValue`, `name`, `form`, `disabled`, `required`, `customError`, `getForm()`,
   `checkValidity()`, `reportValidity()`, `setCustomValidity()`, and `resetValidity()` use the shared form-control
   contract. Reset restores the current declarative `value` default; `readonly` remains focusable
@@ -6848,9 +6963,10 @@ gemstone?: GemstoneKey }`; a valid CSS `color` is used as the
   the selected glow/shine defaults.
 - `accessibleLabel: string = ''` (attribute `aria-label`) — accessible name copied to the internal
   `role="radiogroup"`; attribute presence wins, including an explicitly empty name.
-- `options` and `SwatchOption` remain compatibility aliases for `items` and `SwatchPickerItem`;
-  new code uses the canonical sibling radiogroup vocabulary. The former invisible `label` IDL also
-  remains as a compatibility fallback after `aria-label`/`accessibleLabel`.
+- The 9.x compatibility aliases were removed in 10.0.0: `options` is `items`, the exported
+  `SwatchOption` type is `SwatchPickerItem`, and the former invisible `label` IDL is
+  `accessibleLabel`/`aria-label`. The canonical sibling radiogroup vocabulary is now the only
+  spelling.
 - `disabled: boolean = false` (reflected) — locks the whole picker. Every swatch renders as a real
   `disabled` `<button>`, so it leaves the tab sequence and cannot be activated; arrow/Home/End
   navigation and host `click()` become no-ops; and the swatches dim to `--lr-opacity-disabled` with
@@ -7034,7 +7150,10 @@ leaves the internal role's serialized attribute empty; browsers without the refl
 API keep the string fallback. The relationship tracks host attribute changes and clears when
 unset.
 
-**CSS parts:** `form-control` (outer checkbox/error/hint frame), `base` (compatibility name for the
+**CSS parts:** `form-control` (outer checkbox/error/hint frame), `row` (the row wrapping the
+checkbox owner and the label as siblings — the node to size or align when laying out a column of
+checkboxes, since `base`/`checkbox` below is only the control box and its inline size tracks the box
+rather than the row), `base` (compatibility name for the
 semantic owner; use `checkbox`), `checkbox` (the interactive `role="checkbox"` owner; it is the
 same node as `base`, while the rich default label is its sibling),
 `box` / `control` (the small square showing the checkmark/indeterminate dash; while active it also
@@ -7199,7 +7318,10 @@ restores the current default before making the control pristine again.
 - `help-text` — Shoelace alias for the same hint surface.
 - `error` — custom error content.
 
-**CSS parts:** `form-control` (the outer wrapper around the switch, error and hint), `base` /
+**CSS parts:** `form-control` (the outer wrapper around the switch, error and hint), `row` (the row
+wrapping the switch owner and the label as siblings — the node to size or align when laying out a
+column of switches, since `base`/`switch` below is only the track box and its inline size tracks the
+track rather than the row), `base` /
 `switch` / `wrapper` (the semantic interactive `role="switch"` owner; the rich label is its
 sibling), `track` / `control` (the
 pill-shaped background), `thumb` (the circular knob), `label` (wrapper around the default slot),
@@ -7445,6 +7567,7 @@ Mapped aliases are also live: `--thumb-size`, `--thumb-width`, `--thumb-height`,
 
 ```html
 <lr-slider
+  id="temperature-slider"
   name="temperature"
   min="0"
   max="2"
@@ -7453,14 +7576,11 @@ Mapped aliases are also live: `--thumb-size`, `--thumb-width`, `--thumb-height`,
   hint="Higher values make replies more varied."
   with-markers
   with-tooltip
-  .valueAsNumber=${0.7}
-  .valueFormatter=${(value, handle) => `${value * 100}%`}
-  @lr-input=${(e) => setDraftTemperature(e.detail.value)}
-  @lr-change=${(e) => commitTemperature(e.detail.value)}
 ></lr-slider>
 
 <!-- Two handles, vertical. A name submits two `price` entries. -->
 <lr-slider
+  id="price-slider"
   range
   name="price"
   orientation="vertical"
@@ -7470,8 +7590,17 @@ Mapped aliases are also live: `--thumb-size`, `--thumb-width`, `--thumb-height`,
   min-value="200"
   max-value="800"
   label="Price"
-  @lr-change=${(e) => applyPriceFilter(e.detail.minValue, e.detail.maxValue)}
 ></lr-slider>
+<script type="module">
+  const temperature = document.getElementById("temperature-slider");
+  temperature.valueAsNumber = 0.7;
+  temperature.valueFormatter = (value, handle) => `${value * 100}%`;
+  temperature.addEventListener("lr-input", (e) => setDraftTemperature(e.detail.value));
+  temperature.addEventListener("lr-change", (e) => commitTemperature(e.detail.value));
+
+  const price = document.getElementById("price-slider");
+  price.addEventListener("lr-change", (e) => applyPriceFilter(e.detail.minValue, e.detail.maxValue));
+</script>
 ```
 
 An unset `value` starts at numeric `0`, clamped into the configured domain and step grid. A reset
@@ -8028,15 +8157,23 @@ option layout and defaults to `--lr-checkbox-group-option-gap`.
 `--lr-checkbox-group-invalid-border` (default `var(--lr-color-danger)`) independently retints the
 invalid option-collection border without changing other danger-colored surfaces.
 
-**`value` is a readonly defensive read-out of child state, not an input.** The children are the
-single source of truth. An internal sync recomputes `value` on every child toggle, programmatic
-child `checked`/`value`/`disabled` update, `slotchange`, `name`/`required` change, blur, and
-`form.reset()`. Mutating an obtained array cannot mutate the group.
+**`value` reads as a frozen defensive snapshot of child state, and assigning it mirrors back onto
+the children.** The children remain the single source of truth. An internal sync recomputes `value`
+on every child toggle, programmatic child `checked`/`value`/`disabled` update, `slotchange`,
+`name`/`required` change, blur, and `form.reset()`. Mutating an obtained array cannot mutate the
+group — assign a new array instead.
 Only a checkbox whose nearest `lr-checkbox-group` ancestor is this group contributes; a nested
 group owns its own descendants and form entries. `connectedCallback()` runs that sync before the
 first render.
 
-- **To preselect**, set `checked` on the children: `<lr-checkbox value="a" checked>`.
+Assigning checks every child whose `value` (defaulting to `'on'`) appears in the array and unchecks
+every other one; duplicate entries check that many same-valued children, and values naming no child
+are ignored. `null`/`undefined` clear the selection. It is controlled input, so it emits no
+`lr-change` — only user interaction does. An assignment made before the children exist (the shape of
+a `.value=${...}` binding on first render) is applied once they arrive.
+
+- **To preselect**, either set `checked` on the children (`<lr-checkbox value="a" checked>`) or
+  assign the group's `value`.
 - **To read the selection**, use this property or the `lr-change` event detail.
 - **Give every child a distinct `value`.** `<lr-checkbox>`'s `value` defaults to `'on'`, so a group
   of undifferentiated children submits several identical `FormData` entries and the submitted data
@@ -8077,11 +8214,16 @@ each list mutation; native events have no detail and both aliases carry a frozen
 Native `FocusEvent` `focus`/`blur` are relayed once from the draft and inline editor, preserving
 `relatedTarget`. `lr-add`
 (`detail: { value, values }`, where `value` is the final added token and `values` is the frozen,
-readonly, complete ordered and deduplicated set of tokens added by that commit),
+readonly, complete ordered and deduplicated set of tokens added by that commit — cancelable as of
+10.0.0; `preventDefault()` keeps the tokens out of `value` and leaves the typed draft text in the
+input unchanged so the user can correct it, rather than clearing it),
 `lr-remove`
 (`detail: { value, index }` — cancelable; `preventDefault()` keeps the token in `value`
 unchanged), and `lr-token-edit`
-(`detail: { value, previousValue, index }` — an existing token was edited in place and committed).
+(`detail: { value, previousValue, index }` — an existing token is about to be edited in place —
+cancelable as of 10.0.0; `preventDefault()` keeps the token in `value` unchanged and leaves the
+inline editor open with the user's edited text intact, rather than closing and discarding it).
+All three mutators now share one veto contract; previously only `lr-remove` could be vetoed.
 `lr-invalid` (no detail) is emitted once as a bubbling/composed alias when native validity fails.
 **CSS parts:** `form-control`, `form-control-label`, `input-wrapper`, `token`, `token-label` (the
 token's text, doubling as the roving-focus edit trigger — rendered only while `editable`),
@@ -9139,6 +9281,30 @@ These named interfaces and helper signatures are available to typed integrations
 
 # Data display, dashboards & flow canvas (`components/data/`)
 
+## Breaking changes in 10.0.0
+
+`<lr-calendar>`'s `firstDayOfWeek`/`first-day-of-week` drops the bare `0`–`6` integer form and stops
+defaulting to a hardcoded Monday. The type is now exactly `LyraCalendarFirstDayOfWeek`
+(`'auto'|'sun'|'mon'|'tue'|'wed'|'thu'|'fri'|'sat'`, default `'auto'`), so there is one way to
+express a week start instead of two that had to be sanitized and wrapped against each other, and
+`'auto'` resolves through the same `resolveFirstDayOfWeek()` contract `<lr-date-picker>`/
+`<lr-date-input>` already use. An unset `<lr-calendar>` and an unset `<lr-date-picker>` on the same
+page therefore agree at last — Sunday-first under `en-US`, Monday-first under `fr-FR` — where the
+calendar previously rendered Monday-first everywhere while already formatting its weekday *labels*
+from the locale. Replace `first-day-of-week="1"` with `first-day-of-week="mon"`: a leftover numeric
+value is not mapped or clamped, it is simply an unrecognized token and falls through to Sunday. If
+the locale-independent Monday start was deliberate, keep it by writing `"mon"` explicitly instead of
+relying on the default. There is no `wa-calendar`, so no upstream mirror is affected.
+
+Also corrected in 10.0.0 — not breaking, but visible. A specificity sweep found rules that were
+meant to win yet were losing to another rule in the same shadow stylesheet, so their declarations
+never applied at all. In this family: `<lr-calendar>`'s today cell has a focus ring again (its
+`[data-today]` outline was swallowing it, leaving today's cell pixel-identical focused and at rest)
+and its adjacent-month cells take selection and pointer feedback again; `<lr-table>`'s header cell
+that is both sticky and sortable, `<lr-pagination>`'s page input, `<lr-sequence-strip>`'s selected
+cell and `<lr-flow-canvas>`'s selected edge regain hover/press/focus feedback; and
+`<lr-flow-controls>` honors a `hidden` slotted action button instead of painting it.
+
 ## `lr-sparkline`
 
 Zero-dependency inline SVG trend chart (mirrors `<wa-sparkline>`). Its default allocation is one
@@ -9807,7 +9973,13 @@ cell: (row) => unknown }` —
 - `groupLabel?: (key: string | number, rows: readonly T[]) => unknown` (attribute: false) — custom group
   header content; without it, the group key is rendered as text
 - `expandedContent?: (row: T) => unknown` (attribute: false) — enables a leading expand toggle and
-  renders a full-width detail row beneath expanded records
+  renders a full-width detail row beneath expanded records. The returned content renders inside
+  the component's shadow root, behind the `expanded-cell` part — page CSS cannot reach it, and
+  `::part(expanded-cell)` only reaches the wrapping `<td>` itself, not the descendants this
+  callback returns (the same `::part()` limitation a column's `cell(row)` anchors run into, see
+  `--lr-table-cell-link-color` below). Style such content by returning already-styled elements —
+  inline `style`, or elements that reference this table's own `--lr-*` design tokens, which
+  inherit across the shadow boundary like any custom property
 - `canExpand?: (row: T) => boolean` (attribute: false) — optional per-row gate for expansion
 - `expandedRowKeys: ReadonlySet<string | number> = new Set()` (attribute: false) — consumer-controlled
   expanded state bounded to 10,000 keys; malformed and whitespace-only string keys are omitted while valid
@@ -9859,7 +10031,11 @@ sort properties; server mode leaves them controlled. Other events are `lr-row-cl
 (`detail: { row }`), `lr-load-more` (fired on the "load more" button),
 `lr-priority-columns-visibility-change` (frozen readonly `detail: { visible }`), and `lr-row-expand-toggle`
 (`detail: { row, rowKey }`; the table does not mutate `expandedRowKeys`), and
-`lr-selection-change` (frozen readonly `detail: { rowKeys }`) when selection is enabled, `lr-filter-change`
+`lr-selection-change` (frozen readonly `detail: { rowKeys }`, not cancelable) when selection is
+enabled — fired both from a row activation and from a `selectionMode` flip to `'single'` that coerces
+an existing multi-row selection down to one key (skipped on the very first render, since an
+already-inconsistent initial `selectionMode`/`selectedRowKeys` pairing is a starting state, not a
+live transition), `lr-filter-change`
 (frozen readonly `detail: { text }`), and `lr-page-change` (frozen readonly `detail: { page }`) from the
 filter/pagination surfaces, and `lr-cell-edit` (`detail: { row, columnKey, value }`) for editable
 columns, and `lr-column-resize` (`detail: { columnKey, width }`, `width` in CSS pixels) on every pointer or
@@ -9908,7 +10084,23 @@ no-rows states return the empty element as the shadow root's own root, with no `
 wrapper around it — `::part(base)` does not apply in those two states, only in the filtered-to-zero
 one — and that `empty` disappears entirely once the `empty` slot is filled.
 
-**Themeable custom properties:** `--lr-table-max-height` (default `none`; controls the scrollable
+- `scrollMode: 'self' | 'page' = 'self'` (attribute `scroll-mode`, reflected) — which element
+  scrolls when the table overflows. `'self'` makes `[part="base"]` the scroll container, which is
+  what pairs with `--lr-table-max-height` and makes the sticky header pin inside the table's own
+  viewport. `'page'` hands scrolling back to the document. Needed because a scroll container clips
+  **both** axes — CSS offers no way to scroll one and not the other — so an *uncapped* table that is
+  still `overflow: auto` becomes a sticky containing block that never scrolls, and its header
+  scrolls away with the page. With `'page'` the header's nearest scrollport is the page, so it pins
+  there; the cost is that a table wider than its host overflows the page instead of scrolling
+  inside itself. Named `scrollMode` rather than `scroll` because a `scroll` property would shadow
+  `Element.prototype.scroll()`
+
+**Themeable custom properties:** `--lr-table-cell-color` (default `inherit`),
+`--lr-table-cell-link-color` (default `var(--lr-color-brand)`) and
+`--lr-table-cell-link-hover-color` — an anchor returned from a column's `cell(row)` renders inside
+the component's shadow root, where page CSS cannot reach it and `::part()` cannot select past the
+first compound selector to reach it either, so without these it computes to the UA default link
+blue; set `revert` for the UA default. `--lr-table-max-height` (default `none`; controls the scrollable
 body's `max-block-size`). `--lr-table-heat-tint-lo` (default `var(--lr-color-brand-quiet)`) and
 `--lr-table-heat-tint-hi` (default `var(--lr-color-brand)`) — the `color-mix()` ramp endpoints
 for heat-tint mode's per-cell background, consulted only on columns/rows that define `heatValue`;
@@ -10418,9 +10610,13 @@ number, color?: string, group?: string }` snapshots; malformed/hostile records a
   marking shortened strings with an ellipsis and disclosing omitted input through `[part="limit"]`.
   The returned sequence and records are frozen; reassign `words` after changes.
 - `minFontSize: number = 12` (attribute `min-font-size`) — px, applied to the lowest-weight word;
-  layout clamps positive finite values to at most 512px and uses 1px for invalid/non-positive values
+  a finite value is clamped to `[1, 512]` (so `0`/a negative value floors at `1px`, and an oversized
+  value caps at `512px`); a non-finite value (`NaN`/`Infinity`) falls back to the default `12px`
+  rather than to the `1px` floor
 - `maxFontSize: number = 48` (attribute `max-font-size`) — px, applied to the highest-weight word;
-  normalized by the same 1–512px layout bound (reversed min/max bounds are swapped)
+  clamped/defaulted the same way (a non-finite value falls back to `48px`, not to `1px`); a
+  resulting reversed pair (`minFontSize` greater than `maxFontSize`) is swapped rather than
+  inverting the weight-to-size mapping
 - `scale: 'linear'|'sqrt' = 'linear'` — `sqrt` compresses the weight→font-size mapping so one heavy
   word doesn't dwarf the rest, matching `lr-heatmap`'s `scale` property
 - `wordRotation: 'none'|'mixed' = 'none'` (attribute `word-rotation`, reflected) — `mixed` lets
@@ -10567,6 +10763,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
@@ -10584,6 +10791,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;
@@ -10597,7 +10821,7 @@ row?: number; col?: number; date?: string }`, matched the same way as `annotatio
   persistent ring (independent of keyboard focus) over the matching cell, appends a "Selected: ..."
   description to the host's own `aria-label`, and adds localized selected wording to the keyboard
   announcement when the focused cell is the selection. Purely a controlled property — mirrors
-  `<lr-lite-chart>`'s `selectedIndex`, this component never mutates it itself. Unset (the default,
+  `<lr-lite-chart>`'s `selectedIndices`, this component never mutates it itself. Unset (the default,
   `null`) reproduces today's exact output.
 - `accessibleCells: boolean = false` (attribute `accessible-cells`) — renders `[part="cells"]` with
   at most 400 `[part="cell"]` native buttons around the active cell. The semantic grid exposes the
@@ -10894,16 +11118,30 @@ readonly color, readonly label? }`; `color`
   per-category only. The marker count is reported as its own clause rather than folded into any
   category's count. Unset (the default) changes nothing: no extra legend row, no extra summary clause
 
+- `selectedIndex: number = -1` (attribute `selected-index`) — the currently selected item, or `-1`
+  for none. **Controlled:** activating a cell emits `lr-item-activate` and does *not* move the
+  selection itself, so the consumer stays the single source of truth and the strip cannot drift from
+  a playback index it does not own (its natural companion is `lr-sequence-playback`). Mirrors the
+  shape `lr-lite-chart`'s `selectedIndices` and `lr-heatmap`'s `selectedCell` already establish. An
+  out-of-range or non-integer value selects nothing. The selected cell carries `aria-current="true"`
+  and `data-selected`; the selection is drawn as a ring rather than a background change, because a
+  cell's background is data (its category colour) and tinting it would misreport the category
+
 The single-member `orientation: 'horizontal'` property was **removed in 9.0.0**: nothing read it and
 the stylesheet never mentioned it, so the reflected attribute styled nothing. Delete the attribute;
 the strip has always laid out horizontally.
 
-**Events:** none.
+**Events:** `lr-item-activate` — `detail: { index: number; id: string; item: SequenceStripItem }`,
+fired when a cell is clicked or activated with Enter/Space on the roving-tabindex focus. Not
+cancelable: nothing in the component branches on `defaultPrevented`. Bubbles and composed, like every
+library event.
 
 **Slots:** none.
 
 **CSS parts:** `base` (the root strip, `role="list"`), `cell` (each item's `role="listitem"` cell,
-background-colored by its category and carrying the roving `tabindex`), `marker` (the small bottom
+background-colored by its category, carrying the roving `tabindex`, and activatable by click or
+Enter/Space — it has a pointer cursor plus paired hover/press treatments, and `[data-selected]` when
+it is `selectedIndex`), `marker` (the small bottom
 marker on a cell whose item sets `marker: true`), `tooltip` (the detail tooltip showing the active
 item's label, hidden until a cell is hovered or focused),
 `legend` (the static category key rendered below the strip when `showLegend` is set — `aria-hidden`,
@@ -11838,17 +12076,18 @@ sizes a legend chip on both axes. Otherwise the component consumes shared tokens
 **Optional peer deps:** none.
 
 ```html
-<lr-context-meter
-  label="128K context window"
-  total="128000"
-  .segments=${[
-    { label: 'System prompt', value: 2200, tone: 'neutral' },
-    { label: 'Conversation history', value: 61000, tone: 'brand' },
-    { label: 'Retrieved context', value: 30800, tone: 'warning' },
-  ]}
-></lr-context-meter>
+<lr-context-meter label="128K context window" total="128000"></lr-context-meter>
 
-<lr-context-meter shape="ring" total="128000" .segments=${segments}></lr-context-meter>
+<lr-context-meter shape="ring" total="128000"></lr-context-meter>
+<script type="module">
+  const [meter, ringMeter] = document.querySelectorAll("lr-context-meter");
+  meter.segments = [
+    { label: "System prompt", value: 2200, tone: "neutral" },
+    { label: "Conversation history", value: 61000, tone: "brand" },
+    { label: "Retrieved context", value: 30800, tone: "warning" },
+  ];
+  ringMeter.segments = segments;
+</script>
 ```
 
 An internal visually-hidden semantic node carries `role="meter"` plus `aria-valuenow`,
@@ -11905,8 +12144,15 @@ title, readonly color?, readonly data? }`; `date` is an ISO `YYYY-MM-DD` string
 - `view: CalendarView = 'month'`, where `CalendarView = 'month' | 'agenda'` (reflected) — agenda
   lists the effective visible month's events, date-sorted. Foreign tokens normalize and reflect to
   `month`
-- `firstDayOfWeek: number = 1` (attribute `first-day-of-week`) — sanitized to a finite integer
-  (fallback `1`) and wrapped into `0`–`6`, so a malformed value can't drop days
+- `firstDayOfWeek: LyraCalendarFirstDayOfWeek = 'auto'` (attribute `first-day-of-week`) — which
+  weekday the grid starts on. **Breaking in 10.0.0:** the default was a hardcoded `1` (Monday)
+  regardless of locale; it now derives from the effective locale through the same
+  `resolveFirstDayOfWeek()` contract `<lr-date-picker>`/`<lr-date-input>` already use, so an unset
+  `<lr-calendar>` renders Sunday-first under `en-US` and Monday-first under `fr-FR` instead of
+  disagreeing with a date picker on the same page. **Also breaking in 10.0.0:** the bare `0`–`6`
+  integer form is gone; the value is now one of the shared weekday-name tokens (`'auto'`, then
+  `'sun'` through `'sat'`), which pins the week start independent of locale. Pass `'mon'` to keep
+  the pre-10.0.0 rendering.
 - `accessibleLabel: string = ''` (attribute `aria-label`) — names the host. The nested calendar
   section retains the localized purpose name rather than duplicating an authored host name; when
   set programmatically without a host attribute, this value names the section
@@ -11958,6 +12204,30 @@ opposite default from `lr-stepper`; `horizontal` makes `[part='base']` a horizon
 (the `role="list"` element is in the shadow root and never inherits a host attribute). Read-only
 `itemCount: number` is the live count of direct default-slot `<lr-timeline-item>` children;
 unrelated slotted elements and text nodes are ignored.
+`scale: 'flow' | 'time' = 'flow'` (attribute `scale`, type `LyraTimelineScale`) chooses how items
+are distributed along the main axis. `'flow'` is the default even sequence, where `timestamp` is
+rendered as text but carries no positional meaning. `'time'` positions each item at its true
+proportion of the range, so a gap of weeks and a gap of decades stop looking identical. `'time'`
+needs a definite extent to distribute along — `--lr-timeline-time-extent` (default
+`var(--lr-size-20rem)`), applied as `block-size` when vertical and `inline-size` when horizontal —
+because items are absolutely positioned and a percentage against an auto-sized track resolves to
+zero. `collision: 'overlap' | 'stack' = 'overlap'` (attribute `collision`, type `LyraTimelineCollision`)
+chooses what `scale="time"` does with items landing on nearly the same position: `'overlap'` leaves
+them stacked on one another, `'stack'` steps each colliding item one lane along the **cross** axis
+(indent per lane: `--lr-timeline-collision-offset`, default `var(--lr-space-l)`), which is what a
+dense chronology needs — items within 1.5% of the axis of each other count as colliding, and an
+isolated item returns to lane 0 rather than inheriting a preceding run's depth. There is
+deliberately no `'cluster'` mode: collapsing coincident items into one expandable marker needs a
+selection model and click events this passive component does not have.
+`rangeStart` / `rangeEnd` (`Date | string | number`, attribute: false) pin the axis instead of
+deriving it from the earliest/latest item; a reversed or non-finite pair falls back to the derived
+range. An item with no parseable `timestamp` (including one supplied only through the `timestamp`
+slot, which carries no machine-readable instant) keeps document order and is spread evenly, so a
+partially-timestamped list degrades rather than stacking at the origin. Items sharing an instant
+overlap rather than being fanned into lanes: lane assignment, brushing, zooming and per-event
+selection belong to a denser component than this deliberately passive one. Positions are written to
+each child as a private `--_lr-timeline-item-offset` custom property and removed again on a switch
+back to `'flow'`, so the component still never alters its children's content or structure.
 
 **`lr-timeline-item` properties:** `timestamp?: Date | string | number` (attribute: false — `Date`
 isn't attribute-serializable; invalid input normalizes to unset and renders no timestamp UI),
@@ -12678,6 +12948,11 @@ These named interfaces and helper signatures are available to typed integrations
 }`
 
 - **`components-data-sequence-strip-sequence-strip-contracts`** — Supporting data types and helpers for this component family.
+  `LyraSequenceStripActivateDetail {
+  index: unknown;
+  id: unknown;
+  item: unknown;
+}`
   `SequenceStripCategory {
   id: unknown;
   color: unknown;
@@ -12769,6 +13044,23 @@ These named interfaces and helper signatures are available to typed integrations
 
 # Layout, navigation & structure (`components/layout/`)
 
+## Breaking changes in 10.0.0
+
+**`lr-virtual-list`:** the `lr-visible-range-changed` event is removed — listen for
+`lr-visible-range-change` instead. The detail (`LyraVirtualListRange`), the firing conditions and the
+gesture are all unchanged; only the name moved. The old spelling was the library's only past-tense
+`-changed` event among 58 members of the `-change` family, so a convention-driven `lr-${x}-change`
+listener silently missed it on a component embedded in ten viewers. It is removed outright rather
+than kept as a dual-emitting alias, because the library has no released consumers and an alias is a
+permanent tax paid to protect users who do not exist. Rename the listener; nothing else changes.
+
+Also corrected in 10.0.0 — not breaking, but visible. `<lr-dashboard-grid>`'s cell keeps a focus
+indicator while it is in a collision or drop state: the collision rule owns the outline channel by
+design, but the side effect was that the focus ring vanished entirely during exactly the drag or
+resize a keyboard user most needs it, so the ring is now re-expressed on a second channel. And
+`<lr-card>` honors a `hidden` slotted media child instead of painting it — the component's own
+`display` declaration is author-origin and was beating the UA stylesheet's `[hidden] { display: none }`.
+
 ## Breaking changes in 9.0.0
 
 **`lr-app-rail`:** `mode`'s write side is removed: the accessor is now strictly read-only (always resolves to
@@ -14168,11 +14460,16 @@ is pending.
 between rows.
 
 ```html
-<lr-reorder-list label="Form fields" @lr-reorder=${(e) => console.log(e.detail.order)}>
+<lr-reorder-list label="Form fields">
   <lr-reorder-item value="name">Name</lr-reorder-item>
   <lr-reorder-item value="email">Email</lr-reorder-item>
   <lr-reorder-item value="phone">Phone</lr-reorder-item>
 </lr-reorder-list>
+<script type="module">
+  document
+    .querySelector("lr-reorder-list")
+    .addEventListener("lr-reorder", (e) => console.log(e.detail.order));
+</script>
 ```
 
 **Known gotchas:**
@@ -14463,7 +14760,7 @@ progress` style, and gates `lr-load-more` while a consumer's fetch is in flight.
 **Exported types:** `VirtualListRowHeight = number | 'auto'`;
 `VirtualListSource<T> = readonly T[] | VirtualListIndexedSource<T>` and
 `VirtualListIndexedSource<T> { readonly count: number; itemAt(index): T; keyAt?(index): string |
-number; indexOfKey?(key: string | number): number }`; `VirtualListRange { start: number; end: number }` (the `lr-visible-range-changed`
+number; indexOfKey?(key: string | number): number }`; `VirtualListRange { start: number; end: number }` (the `lr-visible-range-change`
 detail shape); `VirtualListGroup { key: string | number; label?: string; startIndex: number }` — the
 shape consumed by `groups` above; `VirtualListScroll { scrollTop: number; viewportHeight: number }` —
 the `lr-virtual-scroll` detail shape.
@@ -14508,12 +14805,14 @@ math, and any row element can be recycled or removed on the next update.
 **Events:** `lr-load-more` (no detail — fired once per approach to the bottom of the list while
 `has-more` is true and `loading` is false; does not refire on every scroll tick while still near the
 bottom — scrolling back away from the bottom and returning, or `items` growing enough to move the
-window away from the end, re-arms it), `lr-visible-range-changed` (`detail: VirtualListRange`, the
-current visible, non-overscanned item index range — fired only when it actually changes),
+window away from the end, re-arms it), `lr-visible-range-change` (`detail: VirtualListRange`, the
+current visible, non-overscanned item index range — fired only when it actually changes; it was
+spelled `lr-visible-range-changed` before 10.0.0, the only past-tense `-changed` spelling among 58
+`-change`-family events, so a convention-driven `lr-${x}-change` listener silently missed it),
 `lr-virtual-scroll`
 (`detail: VirtualListScroll` — the scroll container moved; emitted from the same animation frame that
 already coalesces native `scroll` events, so a fling produces at most one per frame and none at all
-when the position did not change. Unlike `lr-visible-range-changed`, which only fires on index-range
+when the position did not change. Unlike `lr-visible-range-change`, which only fires on index-range
 changes, this reports _sub-row_ movement, which is what scroll-linked layout needs)
 
 **Slots:** none — all content comes from `renderItem`.
@@ -14544,8 +14843,10 @@ activation target.
 
 **Optional peer deps:** none.
 
-```html
-<lr-virtual-list
+```ts
+import { html } from "lit";
+
+const view = html`<lr-virtual-list
   .items=${sessions}
   .renderItem=${(item, index) => html`
     <lr-conversation-item
@@ -14560,12 +14861,14 @@ activation target.
   ?has-more=${hasMorePages}
   ?loading=${isLoadingMore}
   @lr-load-more=${() => loadNextPage()}
-  @lr-visible-range-changed=${(e) => console.log('visible', e.detail.start, e.detail.end)}
-  @lr-virtual-scroll=${(e) => console.log('scroll top', e.detail.scrollTop)}
-></lr-virtual-list>
+  @lr-visible-range-change=${(e) => console.log("visible", e.detail.start, e.detail.end)}
+  @lr-virtual-scroll=${(e) => console.log("scroll top", e.detail.scrollTop)}
+></lr-virtual-list>`;
 ```
 
 ```ts
+import { html } from "lit";
+
 // No count-sized array: only the current window is read.
 const syntheticRows = {
   count: 100_000,
@@ -14582,15 +14885,17 @@ html`<lr-virtual-list
 ></lr-virtual-list>`;
 ```
 
-```html
-<!-- Sticky group headers: the header is a real row, so the `groups` entries are position anchors
-     only (`label: ''`); the pinned copy remains strictly presentational. -->
-<lr-virtual-list
+```ts
+import { html } from "lit";
+
+// Sticky group headers: the header is a real row, so the `groups` entries are position anchors
+// only (`label: ''`); the pinned copy remains strictly presentational.
+const view = html`<lr-virtual-list
   .items=${rows}
   .groups=${groupStarts /* [{ key: 'Today', label: '', startIndex: 0 }, …] */}
   .renderItem=${(item, index) => (item.isHeader ? headerTemplate(item) : rowTemplate(item))}
   .renderStickyGroup=${(group) => headerTemplate(group)}
-></lr-virtual-list>
+></lr-virtual-list>`;
 ```
 
 Every row is positioned by a `transform: translateY(offset)`, rather than page flow, so only a small
@@ -14946,13 +15251,17 @@ invention (no `wa-*`/`sl-*` counterpart).
   anchors to its block-end edge and does not cover the full height. Has no visual effect while the effective
   presentation resolves to `'inline'`.
 - `label: string = ''` — accessible name for the overlay presentation's `role="dialog"`, used
-  verbatim when set. When empty, falls back to the `header` slot's content: a heading element
-  (`h1`–`h6` or `[role="heading"]`) among the slotted header content wins if present, otherwise the
-  header slot's combined text content is used (mirrors `lr-dialog`'s `detectHeading()` fallback,
-  via `aria-label` rather than `aria-labelledby` since the header content is light DOM while
-  `[part="panel"]` is in shadow DOM). A panel opened with neither `label` nor header content uses
-  the localized `responsivePanel` fallback (`"Panel"` in the default locale), so its dialog is
-  never unnamed. Unused in the inline presentation, which has no dialog semantics to name.
+  verbatim when set — but a plain `aria-label` attribute on the host wins outright over `label`
+  when both are present, the standard ARIA convention for a consumer that wants full control over
+  the announced name (matching `lr-dialog`'s `accessibleLabel` pattern). When both the host
+  `aria-label` and `label` are empty, this falls back to the `header` slot's content: a heading
+  element (`h1`–`h6` or `[role="heading"]`) among the slotted header content wins if present,
+  otherwise the header slot's combined text content is used (mirrors `lr-dialog`'s
+  `detectHeading()` fallback, via `aria-label` rather than `aria-labelledby` since the header
+  content is light DOM while `[part="panel"]` is in shadow DOM). A panel opened with none of a host
+  `aria-label`, `label`, or header content uses the localized `responsivePanel` fallback (`"Panel"`
+  in the default locale), so its dialog is never unnamed. Unused in the inline presentation, which
+  has no dialog semantics to name.
 - `overlayBreakpoint: string = '768px'` (attribute `overlay-breakpoint`) — CSS length compared with
   the component's allocated inline size in `mode="auto"`; at or below it, the effective presentation
   is `'overlay'`.
@@ -15370,19 +15679,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
@@ -15517,6 +15823,30 @@ former brand and active-mix values when unset.
 
 - every `appearance` renders on the _same_ `[part="base"]` element — there's no separate element per
   variant, so a `::part(base)` override applies uniformly regardless of `appearance`.
+- **a card clips, it does not scroll — and it never picks a scroll owner for you.** `[part='base']`
+  stretches to the host's allocated block-size and clips its overflow, which is what keeps a
+  full-bleed `media`/`image` child inside the rounded border. In an auto-sized row the card simply
+  grows and nothing is clipped; give it a _definite_ allocation (a fixed grid row, an explicit
+  `block-size`) and body content taller than that allocation is clipped silently, with no
+  scrollbar. Neither upstream card exposes an overflow, block-size, or scroll hook and neither does
+  this one: the public `body` part already carries the whole decision, and a `::part()` rule from
+  your tree wins over the shadow stylesheet regardless of specificity. A fixed-height tile that
+  must hold more content says so itself:
+
+  ```css
+  .tile-grid {
+    display: grid;
+    grid-template-rows: 12rem;
+  }
+  .tile-grid lr-card::part(body) {
+    overflow: auto;
+    overscroll-behavior: contain;
+  }
+  ```
+
+  `overflow` other than `visible` also zeroes the body's automatic minimum size, so that one
+  declaration is enough — the body shrinks into the tile and scrolls, and `max-block-size` /
+  `scrollbar-gutter` stay available on the same rule. The linked (`href`) card behaves identically.
 - slot-presence (`header`/`media`/`image`/`footer`/`actions`/`header-actions`/`footer-actions`) is
   tracked in JS, not via CSS `:empty` (a
   `[part]` wrapper always contains a literal `<slot>` child, so `:empty` never matches) — the same
@@ -15596,7 +15926,10 @@ row also makes it active.
 **Events:** `lr-open`, `lr-close` (both `detail: undefined`, cancelable — fired before the
 mutation, `preventDefault()` keeps the palette in its current open state), `lr-select`
 (`detail: { command }`, fired before the command's own `onSelect` runs and before the palette
-closes).
+closes), and no-detail `focus`/`blur` events re-dispatched from the host whenever the search input
+gains or loses focus. The `focus`/`blur` bridge is new in 10.0.0: native `focus`/`blur` neither
+bubble nor cross the shadow boundary, so a host-level `el.addEventListener('focus', …)` previously
+never fired at all.
 
 **Slots:** none.
 
@@ -15707,11 +16040,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
@@ -16732,6 +17074,35 @@ These named interfaces and helper signatures are available to typed integrations
 
 # Overlays, status & feedback (`components/overlays/`)
 
+## Breaking changes in 10.0.0
+
+**Breaking (event rename, v10):** `lr-dialog`'s close event is now spelled `lr-close`, and
+`lr-dialog-close` is removed; `lr-drawer`, which inherits the whole dialog lifecycle, loses it too.
+The detail (`DialogCloseReason`), the cancelability, and the position in the `lr-hide` → close →
+`lr-after-hide` sequence are all unchanged — only the name moved, onto the plain spelling
+`lr-tool-select-dialog` and the rest of the library already use. The old name is removed outright
+rather than dual-emitted, because the library has no released consumers and an alias is a permanent
+tax paid to protect users who do not exist. Rename the listener. **Breaking (default change, v10):**
+`lr-progress-ring` gains `showValue`/`show-value`, defaulting to `false`, so a determinate ring no
+longer renders its percentage unless asked. It used to render it unconditionally with no way to
+suppress it short of slotting replacement content, while sibling `lr-progress-bar` has had an opt-in
+`show-value` all along and this reference has always claimed the two share the same value contract;
+they now actually do. Add `show-value` to keep the percentage. The accessible value is unchanged
+either way — `aria-valuetext` still carries the locale-formatted percentage — and slotted replacement
+content still projects with or without the attribute. **Breaking (removal, v10):** `confirm()`'s
+deprecated `tone` option is removed from `ConfirmOptions`; use `variant` (same `'neutral' | 'danger'`
+values, same `'neutral'` default). It was documented as a one-major back-compat alias and `variant`
+already won whenever both were set, so only a caller passing `tone` alone is affected. **New,
+additive, non-breaking:** `lr-popover` gains `disabled` — both `lr-tooltip` and `lr-popover`'s own
+subclass `lr-dropdown` had it and the base did not; `lr-dropdown` now inherits it with byte-identical
+behavior.
+
+Also corrected in 10.0.0 — not breaking, but visible. `lr-alert` really hides a base that is queued
+behind the visible toast window (it renders that base `hidden` and `inert`; `inert` is
+platform-enforced, but `hidden` was doing nothing), and `lr-badge` and `lr-chip` honor a consumer's
+`hidden` slotted adornment. In each case the component's own author-origin `display` declaration was
+beating the UA stylesheet's `[hidden] { display: none }` regardless of specificity.
+
 ## Breaking changes in 9.0.0
 
 **Breaking (type-only, v9):** `lr-toast`'s exported `ToastPlacement`, `ToastCreateOptions`, and
@@ -16762,7 +17133,7 @@ boolean, and all three drive the same code path: `el.show()` is indistinguishabl
 `el.open = true`, and `el.hide()` from `el.open = false`. The property, the reflected attribute and
 the two methods can therefore never disagree, and each method is a no-op when the overlay is already
 in the requested state. `lr-dialog` and `lr-drawer` keep `close(reason)` alongside — `hide()` plus
-the reason string that `lr-dialog-close` carries.
+the reason string that `lr-close` carries.
 
 **Four events, and where the veto sits.**
 
@@ -16786,9 +17157,12 @@ with matching timing _and_ matching cancelability — which also means Lyra 7.x
 relying on the opposite polarity and has to be re-read.
 
 `lr-dialog` and `lr-drawer` also expose cancelable `lr-initial-focus` and `lr-request-close` veto
-points, documented in their sections. Their cancelable `lr-dialog-close` fires **after** `lr-hide`
-and before `lr-after-hide`; it carries the close reason. Vetoing `lr-hide` stops it from firing at
-all.
+points, documented in their sections. Their cancelable `lr-close` fires **after** `lr-hide` and
+before `lr-after-hide`; it carries the close reason as `detail: DialogCloseReason`. Vetoing
+`lr-hide` stops it from firing at all, and `preventDefault()` on `lr-close` itself also vetoes the
+close. The same name is already used by the `lr-tool-select-dialog`/`lr-tool-result-dialog`/
+`lr-tool-approval-dialog` trio, which mirrors this identical detail shape, so one listener covers
+all of them. `lr-drawer` inherits `lr-close` unchanged.
 
 **The top layer.** An open `lr-dialog` or modal `lr-drawer` is promoted into the browser **top layer**
 (through `popover="manual"`) rather than stacked with `z-index`. It therefore escapes every ancestor
@@ -17204,7 +17578,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.
 
@@ -17235,8 +17609,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.
@@ -17363,13 +17737,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
@@ -17385,8 +17764,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
@@ -17475,7 +17854,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", () =>
@@ -17558,7 +17937,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
@@ -17569,8 +17948,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
@@ -17583,7 +17962,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()`.
@@ -18071,6 +18450,11 @@ A click-triggered, light-dismiss floating surface positioned with the shared Flo
   attribute wins by presence, including `aria-label=""`; only when it is absent does the property
   or localized "Popover" ("Menu" when `popupRole` is `menu`) fallback apply
 - `popupRole: 'dialog'|'menu' = 'dialog'` (attribute `popup-role`)
+- `disabled: boolean = false` (reflected, new in 10.0.0) — prevents opening the popover; pointer,
+  keyboard, and programmatic `show()`/`open = true` are all refused while set. Becoming disabled also
+  closes an already-open popover, and initial `disabled` plus `open` normalizes closed in either
+  attribute order. `lr-dropdown` now inherits this from `lr-popover` rather than declaring its own;
+  its consumer-facing behavior is unchanged
 
 To preserve the previous Lyra-shaped defaults explicitly, use
 `placement="bottom-start" distance="4" without-arrow`; origin-aware migration emits those tokens.
@@ -18541,6 +18925,7 @@ A circular progress indicator with the same value contract as `lr-progress-bar`.
 **Properties:** `value: number = 0` (reflected), `max: number = 100`, `indeterminate: boolean = false`
 (reflected), `variant: LyraProgressVariant = 'brand'` (reflected, added in 9.0.0 — matches sibling
 `lr-progress-bar`'s semantic-palette vocabulary: `neutral`/`brand`/`success`/`warning`/`danger`),
+`showValue: boolean = false` (attribute `show-value`),
 `label: string = ''` (the mapped accessible-name property), and
 `accessibleLabel: string = ''` (attribute `accessible-label`; a Lyra compatibility
 accessible-name spelling retained by this progress component, while several sibling components use
@@ -18550,7 +18935,13 @@ visible default-slot text when supplied, then the localized "Progress". Non-fini
 `value`/`max` are normalized (`max <= 0` falls
 back to `100`, `value` clamps to `[0, max]`) rather than producing NaN geometry.
 **Slots:** default — replaces the built-in center label, which otherwise renders the rounded
-percentage (and nothing at all while `indeterminate`).
+percentage **only when `show-value` is set** (and nothing at all while `indeterminate`).
+**Breaking in 10.0.0:** a determinate ring used to render its percentage unconditionally, with no way
+to suppress it short of slotting replacement content. It now gains `showValue`/`show-value` defaulting
+to `false`, exactly matching `lr-progress-bar` — which is what "the same value contract as
+`lr-progress-bar`" above has always claimed but did not deliver. Add `show-value` to keep the
+percentage. `aria-valuetext` still carries it regardless, mirroring `lr-progress-bar`'s own
+independence there, so the accessible value is unaffected.
 Its accessible text uses the same visibility filtering, forwarding-slot mutation/reassignment
 tracking, and explicit-empty host-label precedence as `lr-progress-bar`.
 **Live members:** `indicator: SVGCircleElement | null` returns the rendered indicator circle (or
@@ -19134,7 +19525,6 @@ These named interfaces and helper signatures are available to typed integrations
   confirmLabel: unknown;
   cancelLabel: unknown;
   variant: unknown;
-  tone: unknown;
 }`
 
 - **`components-overlays-dialog-dialog-contracts`** — Supporting data types and helpers for this component family.
@@ -20694,7 +21084,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
@@ -20860,6 +21252,19 @@ behavior warning; direct SVG candidates and the documented animation vocabulary
   used (a11y-tree inconsistencies across engines).
 - Slot/focus microtasks and autoplay never queue new selection work while detached; reconnecting
   starts again from current state rather than replaying stale work.
+- Non-selected candidates are hidden by the component's own `::slotted([hidden])` rule, not by the
+  UA's. `::slotted(*)` sets `display: inline-block` on every candidate, and an author-origin
+  declaration always beats the user-agent `[hidden] { display: none }` — so the rule that restores
+  the native meaning of `hidden` is load-bearing, and an author overriding `display` on
+  `::slotted` content from outside must keep the hidden case at `display: none`.
+  `hidden="until-found"` is exempted, exactly as the UA rule exempts it.
+- **Before script runs, the first candidate is the one that shows.** Selection happens after the
+  first client render and works by setting `hidden`/`aria-hidden` on light-DOM siblings, which Lit
+  hydration never compares, so a server renderer can never produce it. Every candidate after the
+  first is therefore hidden by CSS until a selection has been applied: a server-rendered page — or
+  one whose script never runs — paints one candidate rather than the whole pool. Randomness itself
+  cannot survive SSR (there is no shared seed), so order the pool if a specific candidate should be
+  the pre-hydration one. With `items > 1` the pre-hydration paint is still a single candidate.
 
 ## `lr-tour`
 
@@ -21076,6 +21481,37 @@ These named interfaces and helper signatures are available to typed integrations
 
 # Media, files & maps (`components/media/`)
 
+## Breaking changes in 10.0.0
+
+`<lr-media-card>`'s `alt` becomes optional (`alt?: string`, was `alt: string = ''`), so a decorative
+image is expressible at last. The image render used to fall through `alt`, then `filename`, then a
+localized generic description with `||`, which made an explicit `alt=""` indistinguishable from an
+absent one and published it as `alt="Image attachment"` — there was no way to mark the image
+decorative, which is the one thing
+`alt=""` means in HTML. It now reads `??`, matching `<lr-image-viewer>` and `<lr-document-preview>`,
+which already documented that contract. Omitting `alt` is unchanged; only the value read back from
+an unset property differs (`''` becomes `undefined`), so a consumer comparing `el.alt === ''` should
+read `el.alt ?? ''`. The nested `<video controls>` label deliberately does **not** follow: an empty
+`alt` there would leave an interactive player with no accessible name, and "decorative" is not a
+state a media control can be in, so the video path still falls through to `filename` and the generic
+description.
+
+`<lr-attachment-chip>`'s `lr-preview-request` is no longer cancelable. It was advertised as a veto
+point, but the chip never read `defaultPrevented` and owns no preview default action to cancel — it
+never registers or owns a viewer or overlay, by its own documented contract — so `preventDefault()`
+was a no-op. The flag is removed rather than left as a promise the component cannot keep: a host that
+was calling `preventDefault()` can drop the call, and one that believed the call was suppressing
+something was never being served. `<lr-voice-picker>`'s same-named event belongs to a different
+component, owns a real internal default action, and stays cancelable.
+
+Also corrected in 10.0.0 — not breaking, but visible. `<lr-flag>` no longer paints a full-size
+undecoded image beside its own skeleton while loading; `<lr-video>` no longer keeps a second,
+duplicate controls play button both painted and focusable behind a poster, and it now keeps captions
+for a `<track>` with no `kind` attribute, whose HTML missing-value default is `subtitles`; and
+`<lr-avatar>` and `<lr-image-comparer>` honor a consumer's `hidden` slotted child. In each case the
+component's own author-origin declaration was beating the UA stylesheet's `[hidden] { display: none }`
+regardless of specificity.
+
 ## Breaking changes in 9.0.0
 
 `<lr-media-card>`'s `accessibleLabel` property now defaults to `null` instead of `''`
@@ -21091,7 +21527,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
@@ -21116,11 +21561,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
@@ -21371,6 +21822,22 @@ operations. Its runtime value is the underlying MapLibre map.
   style-required failure and makes no tile/style request. Assign a hosted vector/raster style from
   a provider whose terms fit your application, or an explicitly network-silent style for local
   geometry.
+- `legendGradient: readonly (readonly [number, string])[] = []` (attribute: false, type
+  `LyraMapLegendGradientStop[]`) — renders the legend as a **continuous** gradient bar with endpoint
+  captions instead of (or alongside) the discrete `legend` swatches, which is the standard key for a
+  choropleth whose `interpolate` fill is itself a continuous ramp. Takes the same `[value, color]`
+  stop shape as `choropleth.stops`, so the usual assignment is `map.legendGradient =
+  myChoropleth.stops` and the key cannot drift from the layer it describes. Stops are sorted
+  ascending, bounded to 64, and filtered to finite values carrying a CSS-parsable color; fewer than
+  two usable stops render no bar at all, since a one-stop "gradient" is a flat block that describes
+  nothing. Each stop sits at its true proportion of the value range, so the bar shows the ramp the
+  expression actually produces rather than evenly spacing unevenly-spaced values. Part names
+  (`legend-gradient`, `legend-lo`, `legend-hi`) mirror `lr-heatmap`'s gradient legend, and the bar
+  is `aria-hidden`/`inert` with the captions carrying the meaning. Mirrors under RTL
+- `legendGradientLoLabel: string | null = null` (attribute `legend-gradient-lo-label`),
+  `legendGradientHiLabel: string | null = null` (attribute `legend-gradient-hi-label`) — override
+  the endpoint captions, which otherwise default to the lowest/highest stop value in the component's
+  own locale-aware numeric formatting
 - `legend: readonly LyraMapLegendEntry[] = []` (attribute: false) — immutable defensive snapshots
   of `LyraMapLegendEntry { readonly color: string; readonly label: string; readonly pattern:
 LyraMapLegendPattern }`, where `LyraMapLegendPattern` is `'solid' | 'diagonal' | 'dots' |
@@ -21382,10 +21849,20 @@ omittedCount, truncatedLabelCount, truncated }` result for the latest assignment
   projection renders a localized visible `1–N of M items` summary rather than silently claiming
   the bounded rows are complete.
 - `choropleth?: LyraMapChoroplethLayer` (attribute: false) — `LyraMapChoroplethLayer { sourceId:
-string; geojson: GeoJSON.FeatureCollection; field: string; stops: [number, string][] }` (interpolated
+string; geojson: GeoJSON.FeatureCollection; field: string; stops: [number, string][]; interpolation?:
+'linear' | 'logarithmic' }` (interpolated
   fill-color expression from `field`'s value against `stops`; `stops` must contain at least one
   `[value, color]` pair — an empty array is ignored, leaving whatever fill layer already exists, if
-  any, untouched, rather than being applied)
+  any, untouched, rather than being applied).
+  `interpolation` (type `LyraMapChoroplethInterpolation`, default `'linear'`) chooses how the colour
+  is interpolated between stops. `'logarithmic'` compresses the ramp, which is what a heavy-tailed
+  quantity — price, population, income — needs: on a linear ramp every value below the maximum falls
+  into the first colour band, so the map reads as one flat colour plus a couple of outliers. It
+  emits maplibre's own `['interpolate', ['exponential', 0.25], …]`, exposing an existing capability
+  rather than adding one (maplibre has no `['log']` interpolation type; a sub-1 exponential base is
+  the documented way to weight a ramp toward the low end). **`stops` stay in the data's own units
+  under either mode**, so the legend keeps reading in real values instead of log units — no
+  pre-transforming to log10 and hand-relabelling the legend back
 - `markers: LyraMapMarker[] = []` (attribute: false) — `LyraMapMarker { id?: string; lngLat:
 [number, number]; color?: string; label?: string; unsafeHtml?: string }`; an explicit `id` is
   trimmed and must be nonempty, and the first marker for an explicit ID wins. Markers are reconciled
@@ -21420,6 +21897,37 @@ GeoJSON.FeatureCollection; tone?: 'accent' | 'success' | 'warning' |
   persists across a `dataLayers` reassignment gets its GeoJSON updated in place (`setData()`), one
   that's dropped has its private source/layers removed, and a genuinely new `sourceId` gets new
   resources — nothing leaks on removal, style change, or disconnect.
+- `maxBounds: LyraMapBounds | null = null` (attribute: false) — box the map may not pan outside,
+  `[[west, south], [east, north]]`. Prefer it over calling `map.setMaxBounds()` through the `.map`
+  escape hatch: constraining the camera can wedge maplibre-gl at a sub-1 fractional zoom in a wide
+  container, leaving `getZoom()` returning `null` permanently, every frame throwing from inside the
+  peer's own matrix math, and the canvas never painting again — a blank map, with nothing thrown at
+  the call site to attribute it to. This property applies the same call, then reads the camera back
+  and reverts (restoring zoom and centre) if it did not survive, so the worst case is an
+  unconstrained map plus a dev-mode warning. A malformed box is rejected rather than clamped
+
+**Choropleth and `dataLayers` updates are diffed before they reach the peer.** `setData()`
+unconditionally re-tiles and repaints an entire source, which is invisible on a static map and
+expensive on an animated one. When an update changes only feature *properties* — the values driving
+the colour ramp — the component emits maplibre-gl's incremental `updateData()` instead. The fast
+path is deliberately strict, and needs all of: the same feature count, a `string`/`number` `id` on
+every feature in the same order, and geometry that is the **same object** as last time (not merely
+deep-equal). Structurally comparing polygon rings would cost about what the re-tile costs, and a
+false positive would paint stale geometry. Reuse your geometry objects across frames — the
+efficient way to build an animation anyway — and the fast path applies; otherwise it falls back to
+`setData()` with no change in behaviour. Peers predating `updateData()` always take the old path.
+
+**Feature properties are tiled, and therefore bounded in numeric magnitude.** MapLibre GL tiles
+every GeoJSON source through a worker into a protobuf vector tile, so a property carrying a huge
+integer throws *inside that worker* — "Given varint doesn't fit into 10 bytes". That throw is not
+catchable by your app and not a rejected promise; it reaches you only as an opaque message on
+`lr-map`'s own error handler, while the rest of the layer still paints, so one bad feature in a
+large collection is invisible until someone walks the data by hand. Both `choropleth.geojson` and
+`dataLayers[].geojson` are now pre-scanned (first 10,000 features) and any numeric property beyond
+`Number.MAX_SAFE_INTEGER` draws a dev-mode warning naming the feature and the property. Carry a
+reduced figure in the feature — a log, a bucket, an index — and keep the exact value in your own
+payload beside the map.
+
 - `label: string = ''` — purpose-specific accessible name for MapLibre's actual focusable canvas.
   A nonempty host `aria-label` remains on the host and is not duplicated onto the canvas; the canvas
   uses `label` or the localized map name. An explicitly empty host `aria-label` is preserved as an
@@ -21442,13 +21950,20 @@ shared `maplibre-gl` import without constructing a map or allocating a WebGL con
 an element.
 
 **Events:** `lr-map-load` (fired once, after the underlying map's own `'load'`), `lr-map-click`
-(frozen `detail: { readonly lngLat: readonly [lng, lat], readonly feature? }`; the tuple and any
-hit GeoJSON feature are detached and recursively frozen — feature is only populated if a
-choropleth fill layer exists and was hit)
-
-**Slots:** none.
-
-**CSS parts:** `base`, `container`, `legend`, `legend-swatch`, `legend-limit`, `marker`, `popup`,
+(frozen `detail: { readonly lngLat: readonly [lng, lat], readonly feature?, readonly origin?,
+readonly sourceId? }`; the tuple and any hit GeoJSON feature are detached and recursively frozen).
+`feature` resolves against the choropleth fill layer **and** every applied `dataLayers`
+fill/line/circle layer, topmost first — so a shape painted through `dataLayers` is identifiable
+instead of being indistinguishable from empty space. `origin` is `'choropleth'` or `'data-layer'`,
+and `sourceId` carries the authored `dataLayers[].sourceId` for a data-layer hit; both are
+`undefined` whenever `feature` is
+
+**Slots:** `legend` — custom legend content, rendered inside the legend panel's own layout so it
+stays positioned with the map instead of floating beside it. Supplying it opens the panel even
+when `legend` and `legendGradient` are both empty.
+
+**CSS parts:** `base`, `container`, `legend`, `legend-swatch`, `legend-gradient`, `legend-lo`,
+`legend-hi`, `legend-limit`, `marker`, `popup`,
 `popup-content`, `popup-close-button`, `attribution`, `attribution-toggle`, `error`.
 `legend` is a localized `role="group"` containing a real list associated to the map canvas with
 `aria-describedby`; each entry is a `listitem`, decorative swatches are inert/accessibility-hidden,
@@ -22050,7 +22565,7 @@ to populate it: set `file` to a real `File` (fresh from a picker/drop), from whi
 `mime-type`/`thumbnail-src` props instead, for reconstructing a chip from server-persisted
 attachment metadata after a page reload, when no real `File` object exists any more. `file` always
 wins when both are present. When a real `File` or `preview-src` is available, the chip offers a
-localized action that emits a cancelable `lr-preview-request`; it never registers or owns a viewer
+localized action that emits a plain, non-cancelable `lr-preview-request`; it never registers or owns a viewer
 or overlay, so the host composes the desired preview surface.
 
 **Properties:**
@@ -22109,9 +22624,12 @@ derived from `` `${file.name}:${file.size}:${file.lastModified}` ``; when neithe
 generated internal id is used as a last resort.
 
 **Events:** `lr-remove` (`detail: { attachmentId }`, only rendered while `removable`), `lr-retry`
-(`detail: { attachmentId }`, only rendered while `status="error"`), and cancelable
-`lr-preview-request` (`detail: { attachmentId, name, mimeType, src }`). Preventing the preview
-request is a host veto point; the chip itself has no preview default action.
+(`detail: { attachmentId }`, only rendered while `status="error"`), and
+`lr-preview-request` (`detail: { attachmentId, name, mimeType, src }`) — a plain, non-cancelable
+notification that the preview action was activated. **Breaking in 10.0.0:** this event was
+advertised as cancelable, but the chip never read `defaultPrevented` and owns no preview default
+action to veto (it never registers or owns a viewer/overlay), so `preventDefault()` was a no-op.
+The flag is gone rather than left as a promise the component cannot keep.
 
 **Slots:** none.
 
@@ -22276,13 +22794,18 @@ final.
 - `mimeType: string = ''` (attribute `mime-type`) — drives auto-detection when `kind` is unset.
 - `filename: string = ''` — shown in the file-chip fallback, used as the download link's suggested
   filename, and folded into the accessible name.
-- `alt: string = ''` — alt text for the image case (and reused as a video label fallback). Falls
-  back to `filename`, then a generic per-kind description.
-- `accessibleLabel: string = ''` (attribute `aria-label`) — a declarative attribute names the host
-  as a whole while its nested button/link keeps a purpose-specific localized action name. A
-  property-only assignment can override the nested action when no host label is present. Image alt
-  text and the native video's own purpose label remain independent; an explicitly empty host still
-  leaves every interactive descendant named.
+- `alt?: string` — alt text for the image case (and reused as a video label fallback). Unset falls
+  back to `filename`, then a generic per-kind description. An explicit `alt=""` survives to the
+  rendered `<img alt="">`, which is the HTML idiom for a decorative image — same contract as
+  `<lr-image-viewer>` and `<lr-document-preview>`. The `<video>` case is deliberately outside that
+  carve-out: an empty `alt` there still falls through to `filename`/the generic description, because
+  an empty accessible name would leave an interactive player unnamed rather than mark it decorative.
+- `accessibleLabel: string | null = null` (attribute `aria-label`) — a declarative attribute names
+  the host as a whole while its nested button/link keeps a purpose-specific localized action name. A
+  property-only assignment can override the nested action when no host label is present. An explicit
+  empty string behaves like the unset `null` default — both fall through to the generated
+  purpose-specific name. Image alt text and the native video's own purpose label remain independent;
+  an explicitly empty host still leaves every interactive descendant named.
 - `maxHeight: string = ''` (attribute `max-height`) — a CSS length (e.g. `"16rem"`); once set,
   overrides the `--lr-media-card-max-height` custom property for this instance only (applied
   inline on `[part="base"]`, so it reliably wins over a `:host{}`-declared default from outside the
@@ -22348,12 +22871,23 @@ sizing), `--lr-focus-ring-*`, `--lr-transition-fast`.
 **Optional peer deps:** none.
 
 ```html
-<lr-media-card kind="image" src="https://example.com/photo.jpg" alt="Screenshot" filename="photo.jpg"
-  @lr-media-open=${(e) => openLightbox(e.detail.src)}
-></lr-media-card>
-<lr-media-card kind="file" src="https://example.com/report.pdf" filename="report.pdf"
-  @lr-before-media-download=${(e) => shouldUseNativeDownload || e.preventDefault()}
+<lr-media-card
+  id="image-card"
+  kind="image"
+  src="https://example.com/photo.jpg"
+  alt="Screenshot"
+  filename="photo.jpg"
 ></lr-media-card>
+<lr-media-card id="file-card" kind="file" src="https://example.com/report.pdf" filename="report.pdf">
+</lr-media-card>
+<script type="module">
+  document
+    .getElementById("image-card")
+    .addEventListener("lr-media-open", (e) => openLightbox(e.detail.src));
+  document
+    .getElementById("file-card")
+    .addEventListener("lr-before-media-download", (e) => shouldUseNativeDownload || e.preventDefault());
+</script>
 ```
 
 **Safe-URL checking.** `src` is validated by internal sink-specific helpers before it's
@@ -22394,8 +22928,8 @@ true}))` still invokes the anchor's native activation behavior if nothing calls
 
 ## `lr-attachment-trigger`
 
-A compact attach affordance designed for a chat composer's leading slot (see `lr-chat-composer`'s
-own `leading` slot, which this drops straight into, though it has no code dependency on it). First-
+A compact attach affordance designed for a chat composer's start slot (see `lr-chat-composer`'s
+own `start` slot, which this drops straight into, though it has no code dependency on it). First-
 party invention (no Web Awesome equivalent). Its shape adapts to how many attachment `capabilities`
 are configured: exactly one renders a single plain icon button; more than one renders a small
 anchored menu (composed from `lr-dropdown`/`lr-menu`/`lr-menu-item`) listing each
@@ -22453,10 +22987,13 @@ hidden via CSS by default, exposed as a part only so a consumer can override tha
 **Optional peer deps:** none.
 
 ```html
-<lr-attachment-trigger .capabilities=${['files', 'image', 'camera']} accept=".pdf,.docx"
-  @lr-files=${(e) => queueFiles(e.detail.capability, e.detail.files)}
-  @lr-camera-request=${openCameraFlow}
-></lr-attachment-trigger>
+<lr-attachment-trigger accept=".pdf,.docx"></lr-attachment-trigger>
+<script type="module">
+  const trigger = document.querySelector("lr-attachment-trigger");
+  trigger.capabilities = ["files", "image", "camera"];
+  trigger.addEventListener("lr-files", (e) => queueFiles(e.detail.capability, e.detail.files));
+  trigger.addEventListener("lr-camera-request", openCameraFlow);
+</script>
 ```
 
 **Known gotchas:**
@@ -22561,14 +23098,14 @@ variant's quiet tint.
 <lr-avatar label="Assistant"><svg slot="icon" viewBox="0 0 24 24"><!-- role glyph --></svg></lr-avatar>
 
 <!-- Far down a long list: defer the request, fall back to a glyph, and report a broken URL. -->
-<lr-avatar
-  image="/users/7/photo.jpg"
-  label="Ada Lovelace"
-  loading="lazy"
-  @lr-error=${(e) => reportBrokenAvatar(e.detail.image)}
->
+<lr-avatar id="lazy-avatar" image="/users/7/photo.jpg" label="Ada Lovelace" loading="lazy">
   <svg slot="icon" viewBox="0 0 24 24"><!-- fallback glyph --></svg>
 </lr-avatar>
+<script type="module">
+  document
+    .getElementById("lazy-avatar")
+    .addEventListener("lr-error", (e) => reportBrokenAvatar(e.detail.image));
+</script>
 ```
 
 **Known gotchas:**
@@ -23147,7 +23684,9 @@ unsupported or unresolved targets report `false` through the return value and `l
 `lr-rate-change` (`detail: { rate }`), `lr-cue-change`
 (`detail: { readonly cueId, readonly index }`; `cueId` is `null` and `index` is `-1` when no cue is active),
 `lr-highlight-activate` (`detail: { highlightId }`), `lr-anchor-result` (`detail: {
-found }`), `lr-search-change` (`detail: { query, matchCount, activeIndex }`), and
+found }`), `lr-search-change` (`detail: { query, matchCount, matchCountExact, activeIndex }`;
+`matchCountExact` is always `true` — `search()` matches over the already-loaded `cues` array with no
+additional ceiling), and
 `lr-render-error` (`detail: { error }`). The native `ended`, `error`, `loadedmetadata`, `pause`,
 `play`, `timeupdate`, and `volumechange`
 events are also relayed exactly once from the host as native `Event` instances. Like the original
@@ -23552,6 +24091,7 @@ These named interfaces and helper signatures are available to typed integrations
   `setFlagUrlResolver(/* public names: value */): unknown`
 
 - **`components-media-flag-language-map-contracts`** — Supporting data types and helpers for this component family.
+  `alpha3ToAlpha2(/* public names: code */): unknown`
   `languageToCountry(/* public names: language */): unknown`
   `localeNativeName(/* public names: tag */): unknown`
 
@@ -23575,9 +24115,19 @@ These named interfaces and helper signatures are available to typed integrations
 
 - **`components-media-map-map-loader-contracts`** — Supporting data types and helpers for this component family.
   `loadMaplibre(): unknown`
+  `MapLibreGeoJsonDiff {
+  update: unknown;
+  id: unknown;
+  addOrUpdateProperties: unknown;
+  key: unknown;
+  value: unknown;
+  removeProperties: unknown;
+}`
   `MapLibreGeoJsonSource {
   setData: unknown;
   data: unknown;
+  updateData: unknown;
+  diff: unknown;
 }`
   `MapLibreMapCapability {
   getCanvas: unknown;
@@ -23590,6 +24140,8 @@ These named interfaces and helper signatures are available to typed integrations
   setZoom: unknown;
   zoom: unknown;
   resize: unknown;
+  setMaxBounds: unknown;
+  bounds: unknown;
   remove: unknown;
   on: unknown;
   type: unknown;
@@ -23649,11 +24201,13 @@ These named interfaces and helper signatures are available to typed integrations
 }`
 
 - **`components-media-map-map-contracts`** — Supporting data types and helpers for this component family.
+  `buildGeoJsonPropertyDiff(/* public names: previous, next */): unknown`
   `LyraMapChoroplethLayer {
   sourceId: unknown;
   geojson: unknown;
   field: unknown;
   stops: unknown;
+  interpolation: unknown;
 }`
   `LyraMapGeoJsonDataLayer {
   sourceId: unknown;
@@ -23671,6 +24225,8 @@ These named interfaces and helper signatures are available to typed integrations
   setZoom: unknown;
   zoom: unknown;
   resize: unknown;
+  setMaxBounds: unknown;
+  bounds: unknown;
 }`
   `LyraMapLegendEntry {
   color: unknown;
@@ -23808,6 +24364,32 @@ property).
 - `max: number | null = null`, `min: number | null = null` — finite value-axis bounds. They apply to
   the cartesian value axis selected by `indexAxis`, or the radial `r` scale; non-finite writes are
   omitted before Chart.js sees them
+- `annotations: readonly LyraChartAnnotation[] = []` (attribute: false) — declarative reference
+  lines and shaded bands: a threshold, an event year, a regime change, a highlighted period.
+  `LyraChartAnnotation { axis?: 'x' | 'y'; value?: number; from?: number; to?: number; label?:
+  string; tone?: LyraVariant }` — `tone` is the shared `LyraVariant` vocabulary
+  (`'neutral' | 'brand' | 'success' | 'warning' | 'danger'`), not a chart-local copy. A finite `value` renders
+  a reference line on that axis; a finite `from`/`to` pair renders a band bounded on that axis and
+  spanning the other. `axis` defaults to `'y'`. An entry with neither (or non-finite numbers) is
+  dropped rather than handed to Chart.js; a reversed range is normalized. Labelled entries are
+  included in the generated accessible description, mirroring `lr-heatmap` — the label is
+  consumer-supplied text and so is not localized, and an unlabelled line has no nameable meaning to
+  announce. Needs the optional `chartjs-plugin-annotation` peer, loaded on first actual demand, so a
+  page with no annotated charts never downloads it; without it the chart still renders and a single
+  console warning explains the no-op. The plugin is registered globally, like `chartjs-plugin-zoom`
+  and unlike `chartjs-plugin-datalabels`: it draws nothing unless a chart supplies annotation
+  options, so the registration is unobservable to charts that set none, and registration is also
+  what installs the plugin's own element defaults
+- `scaleType: 'linear' | 'logarithmic' = 'linear'` (attribute `scale-type`, type
+  `LyraChartScaleType`) — scale type for the **value** axis; the categorical axis is never
+  affected. `'logarithmic'` plots data spanning several orders of magnitude (prices, latency
+  percentiles, file sizes) honestly, where a linear axis collapses everything below the maximum
+  into the baseline. Inherited by `lr-line-chart`, `lr-scatter-chart` and `lr-bar-chart`, and
+  applied to the secondary `y2` axis too when one is present. A logarithmic axis cannot represent
+  zero (`log(0)` is `-Infinity`), so `beginAtZero` is not forwarded in that mode and non-positive
+  points are dropped by Chart.js's own log scale. Chart.js rejects an unregistered scale type at
+  construction, so `LogarithmicScale` is registered with the core — it ships inside the `chart.js`
+  module already loaded, adding no download weight
 - `plugins: LyraChartPlugin[] = []` — peer-neutral per-instance Chart.js plugin structures,
   combined without duplicates with Lyra's
   on-demand data-label plugin and any `config.plugins` entries
@@ -23839,9 +24421,9 @@ property).
   non-integer, negative, and out-of-range indexes are discarded. The component writes the accepted
   legend-toggle snapshot back to this property so a host can persist it, and a programmatic write
   reconciles Chart.js and the DOM legend silently without emitting either legend-visibility event.
-- `withoutLegend: boolean = false` (attribute `without-legend`) — the legend shows by default;
-  set this to hide it. Renders a wrapping DOM legend (when shown) whose keyboard-operable buttons
-  toggle dataset visibility. The DOM surface preserves long public labels that a canvas legend
+- `withoutLegend: boolean = false` (attribute `without-legend`, reflected) — the legend shows by
+  default; set this to hide it. Renders a wrapping DOM legend (when shown) whose keyboard-operable
+  buttons toggle dataset visibility. The DOM surface preserves long public labels that a canvas legend
   would clip. Its pressed state follows `hiddenDatasets` whenever that controlled snapshot is
   defined, otherwise the effective dataset's declarative `hidden` value before Chart.js is ready
   and across chart type/plugin rebuilds.
@@ -23876,8 +24458,6 @@ property).
   by radar/polar-area are out of scope)
 - `withoutAnimation: boolean = false` (attribute `without-animation`, reflected) — disables Chart.js
   construction animation; reduced-motion preference also disables it regardless of this value
-- `withoutLegend: boolean = false` (attribute `without-legend`, reflected) — hides the legend;
-  it wins over the positive `legend` alias
 - `withoutTooltip: boolean = false` (attribute `without-tooltip`, reflected) — disables the
   Chart.js tooltip plugin for this instance
 - `dataLabels: boolean = false` (attribute `data-labels`) — draws each point's value on the chart via
@@ -24111,7 +24691,7 @@ requested enhancement is disabled and a localized static `feature-warning` is vi
 announced. In particular, unavailable data labels do not remove generated table totals.
 
 ```html
-<lr-chart type="line" x-label="Day" y-label="kWh" legend></lr-chart>
+<lr-chart type="line" x-label="Day" y-label="kWh"></lr-chart>
 <script>
   const c = document.querySelector('lr-chart');
   c.labels = ['Mon', 'Tue', 'Wed'];
@@ -24156,7 +24736,7 @@ announced. In particular, unavailable data labels do not remove generated table
   off-screen, property changes that would otherwise trigger a Chart.js redraw are skipped (and a
   single redraw fires once it re-enters the viewport). Independently, `updated()` only reaches
   Chart.js when at least one of `type`, `labels`, `datasets`, `description`, `grid`, `indexAxis`,
-  `label`, `hiddenDatasets`, `legend`, `legendPosition`, `min`, `max`, `plugins`, the internal resolved auto legend
+  `label`, `hiddenDatasets`, `legendPosition`, `min`, `max`, `plugins`, the internal resolved auto legend
   position, `valueFormatter`, `formatter`, `area`, `height`, `xLabel`, `yLabel`, `y2Label`, `beginAtZero`,
   `stacked`, any `without*` control, `dataLabels`, `stackTotals`, `config`, the parsed
   slotted config, `zoom`, `locale`, `strings`, or the internal loading state actually changed in
@@ -24263,11 +24843,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
@@ -24414,7 +25004,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`
@@ -24455,7 +25046,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'];
@@ -24487,6 +25078,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
@@ -24733,6 +25326,7 @@ These named interfaces and helper signatures are available to typed integrations
 
 - **`components-charts-chart-chart-core-loader-contracts`** — Supporting data types and helpers for this component family.
   `ChartJsModule {
+    LogarithmicScale: unknown;
     Chart: unknown;
     defaults: unknown;
     plugins: unknown;
@@ -24767,6 +25361,9 @@ These named interfaces and helper signatures are available to typed integrations
   `ChartPluginCapability {
     id: unknown;
   }`
+  `loadAnnotationPlugin(/* public names: importAnnotation */): unknown`
+  `loadChartAndAnnotation(/* public names: loadChart, importAnnotation */): unknown`
+  `loadChartJsWithAnnotationResult(/* public names: importAnnotation */): unknown`
 
 - **`components-charts-chart-chart-legend-visibility-contracts`** — Supporting data types and helpers for this component family.
   `LyraChartLegendVisibilityChangeDetail {
@@ -24801,6 +25398,14 @@ These named interfaces and helper signatures are available to typed integrations
 
 - **`components-charts-chart-chart-contracts`** — Supporting data types and helpers for this component family.
   `lockChartType(/* public names: ctor, value */): unknown`
+  `LyraChartAnnotation {
+    axis: unknown;
+    value: unknown;
+    from: unknown;
+    to: unknown;
+    label: unknown;
+    tone: unknown;
+  }`
   `LyraChartArea {
     top: unknown;
     left: unknown;
@@ -25070,11 +25675,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 -->
@@ -25084,6 +25689,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
@@ -25168,8 +25778,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
@@ -26002,7 +26613,9 @@ current page and
 `zoom: number = 1` is clamped to `0.25`–`4`. `maxHeight: string = ''` (attribute `max-height`) is a
 CSS length that, once set, overrides `--lr-pdf-viewer-height` — the block size of the virtualized
 page list — declaratively, writing it inline on `[part="base"]`; invalid CSS `max-height` values,
-declaration breaks, and `url()` are ignored. `anchorKinds: readonly LyraAnchorKind[] = ['page',
+declaration breaks, and `url()` are ignored. `workerSrc: string = ''` (attribute `worker-src`) is the
+URL of the PDF.js web worker chunk — see **Configuring the PDF.js worker** below.
+`anchorKinds: readonly LyraAnchorKind[] = ['page',
 'text-quote', 'region']` (this viewer's supported `LyraAnchor.kind` values for the shared
 anchor-target contract). The other inherited anchor-target properties are `highlights:
 LyraHighlight[] = []` (property only; reassign after mutation), `activeHighlightId: string | null =
@@ -26019,7 +26632,8 @@ nonnegative dimensions.
 - `lr-load` — `detail: { pageCount }` — the document reached `ready`. `page` is reset to `1` first.
 - `lr-page-change` — `detail: { page, pageCount }` — fired for scroll-driven page crossings as well
   as `page` assignments and `nextPage()`/`previousPage()`/`goToPage()`.
-- `lr-zoom-change` — `detail: { zoom }`.
+- `lr-zoom-change` — `detail: { zoom }` — fired for `zoom` assignments as well as
+  `zoomIn()`/`zoomOut()`. Never fired for the initial `1`, only for a transition away from it.
 - `lr-search-change` — `detail: { query, matchCount, matchCountExact, activeIndex }` — from `search()`/`searchNext()`/
   `searchPrevious()`/`clearSearch()` and effective-locale re-evaluation. A `src` change invalidates document-relative matches and emits
   the canonical reset `{ query: '', matchCount: 0, matchCountExact: true, activeIndex: -1 }`.
@@ -26034,6 +26648,30 @@ nonnegative dimensions.
   `pageViewerSnapshot` (`identity`, `status`, `page`, `pageCount`). `identity` changes for every load,
   including same-count replacements.
 
+**`lr-page-change`/`lr-zoom-change` are state broadcasts, not user-intent signals.** This differs
+deliberately from the same-named `<lr-pagination>` event and from `<lr-pan-zoom>`'s `lr-zoom-change`,
+and the distinction is worth internalizing before wiring a handler. Pagination and pan-zoom are
+*controlled*: pagination never mutates its own `page`, so its event is a request the host applies,
+and pan-zoom's `zoom` is bound by a parent, so echoing a programmatic write back would feed a loop.
+This viewer instead *owns* `page` and `zoom` — scrolling the page list changes `page` with no
+consumer action at all — so there is no useful "the user did this" subset to isolate, and every
+accepted transition is announced identically: scrolling, `nextPage()`/`previousPage()`/`goToPage()`,
+`zoomIn()`/`zoomOut()`, anchor resolution, the reset to page 1 when a new `src` finishes loading,
+and a plain `viewer.page = 3` / `viewer.zoom = 2` assignment. A handler that mirrors the event back
+into the property it came from is therefore idempotent rather than looping, but it is also
+redundant — read the property, or `pageViewerSnapshot`, instead.
+
+A write that clamps or rounds back onto the value already in effect is not a transition and stays
+silent: on a 3-page document already showing page 1, `viewer.page = -7` and `viewer.page = 1.4` both
+settle on page 1 and emit nothing, and `viewer.zoom = 999` at 4× emits nothing.
+
+For page-addressed integrations prefer the atomic `pageViewerSnapshot` /
+`lr-page-viewer-state-change` channel over this pair: it carries page, count, load status and
+document `identity` together, and a late subscriber can read the current value synchronously instead
+of having missed the announcement. `<lr-page-rail>` binds that channel for any viewer exposing
+`pageViewerSnapshot` — including this one — and falls back to `lr-load`/`lr-page-change` only for
+older structural sources that do not.
+
 **Methods:** `nextPage()`, `previousPage()`, `zoomIn()`, and `zoomOut()` update the corresponding
 controlled state within its supported range. `getPageText(page)` resolves the raw reading-order text
 of one page (per-page LRU-cached, 64 pages), rejecting on no loaded document or an out-of-range page.
@@ -26091,6 +26729,39 @@ a PDF is opened. An absent `pdfjs-dist` fails closed and renders
 `[part="error"]` with the localized `pdfViewerMissingLibrary` message — there is no partial PDF
 rendering without it.
 
+**Configuring the PDF.js worker.** PDF.js renders in a web worker and rejects every document with
+`No "GlobalWorkerOptions.workerSrc" specified.` until it has been told where that worker lives. The
+worker is a separate file inside the peer (`pdfjs-dist/build/pdf.worker.min.mjs`) that only the
+application's own bundler can turn into a real URL — a bare package specifier does not resolve in a
+browser without an import map, and resolving it against this library's own module URL would point
+into `@aceshooting/lyra-ui`'s files, where no worker exists. So a bundled application supplies it,
+either way round:
+
+```ts
+// 1. Per element, through the public property/attribute.
+import workerUrl from 'pdfjs-dist/build/pdf.worker.min.mjs?worker&url'; // Vite; see your bundler
+const viewer = document.querySelector('lr-pdf-viewer');
+viewer.workerSrc = workerUrl;
+// or, declaratively: <lr-pdf-viewer worker-src="/assets/pdf.worker.min.mjs"></lr-pdf-viewer>
+
+// 2. Once for the whole application, on PDF.js's own singleton, before any viewer loads a document.
+import { GlobalWorkerOptions } from 'pdfjs-dist';
+GlobalWorkerOptions.workerSrc = workerUrl;
+```
+
+`workerSrc` accepts a document-relative URL (resolved against the document base) as well as an
+absolute one; only `http:`, `https:`, `blob:` and `file:` URLs are accepted, and anything else — a
+`javascript:` or `data:` URL in particular — is ignored rather than handed to `new Worker()`.
+
+`GlobalWorkerOptions` is PDF.js's process-wide singleton and the PDF.js module itself is loaded once
+per page, so `workerSrc` is applied only while that singleton is still unset. Two consequences worth
+knowing before reaching for the per-element form: a worker the application configured itself is never
+overwritten, and when several viewers carry different `workerSrc` values only the first one to load
+PDF.js takes effect for the whole page. Assigning `workerSrc` after PDF.js has already loaded is not
+silently dropped — it is re-applied on the next load — but it still cannot displace an
+already-configured worker. Option 2 above is the right choice for an application that wants one
+explicit worker everywhere.
+
 Remote resources are capped at 25 MB; exceeding it surfaces the localized
 `documentPreviewResourceTooLarge` message instead of the PDF.
 
@@ -26530,9 +27201,12 @@ each tone's highlighted-cell background. `--lr-notebook-viewer-highlight-active-
 `text/plain`).
 
 ```html
-<lr-notebook-viewer .notebook=${result} max-height="30rem"
-  @lr-load=${(e) => console.log(e.detail.cellCount, 'cells')}
-></lr-notebook-viewer>
+<lr-notebook-viewer max-height="30rem"></lr-notebook-viewer>
+<script type="module">
+  const viewer = document.querySelector("lr-notebook-viewer");
+  viewer.notebook = result;
+  viewer.addEventListener("lr-load", (e) => console.log(e.detail.cellCount, "cells"));
+</script>
 ```
 
 A notebook major version outside 4.0–4.5, an invalid shape, or more than 2,000 cells renders a
@@ -27152,6 +27826,79 @@ These named interfaces and helper signatures are available to typed integrations
   children: unknown;
 }`
 
+- **`components-viewers-pptx-viewer-pptx-loader-contracts`** — Supporting data types and helpers for this component family.
+  `adaptPptxViewer(/* public names: value */): unknown`
+  `getPptxRenderer(): unknown`
+  `loadPptxRenderer(/* public names: importer */): unknown`
+  `PptxRendererModule {
+  PptxViewer: unknown;
+  open: unknown;
+  input: unknown;
+  container: unknown;
+  options: unknown;
+  RECOMMENDED_ZIP_LIMITS: unknown;
+}`
+  `PptxSearchHighlightHandle {
+  dispose: unknown;
+}`
+  `PptxTextSearchResult {
+  slideIndex: unknown;
+  nodeId: unknown;
+  matchStart: unknown;
+  matchEnd: unknown;
+  text: unknown;
+}`
+  `PptxThumbnailHandle {
+  ready: unknown;
+  dispose: unknown;
+}`
+  `PptxViewerAdapter {
+  slideCount: unknown;
+  currentSlideIndex: unknown;
+  goToSlide: unknown;
+  index: unknown;
+  searchText: unknown;
+  query: unknown;
+  options: unknown;
+  matchCase: unknown;
+  highlightSearchResult: unknown;
+  result: unknown;
+  scrollIntoView: unknown;
+  renderThumbnailToContainer: unknown;
+  container: unknown;
+  width: unknown;
+  clearSearchHighlights: unknown;
+  subscribe: unknown;
+  listener: unknown;
+  event: unknown;
+  destroy: unknown;
+}`
+  `PptxViewerApi {
+  slideCount: unknown;
+  currentSlideIndex: unknown;
+  goToSlide: unknown;
+  index: unknown;
+  searchText: unknown;
+  query: unknown;
+  options: unknown;
+  matchCase: unknown;
+  highlightSearchResult: unknown;
+  result: unknown;
+  scrollIntoView: unknown;
+  renderThumbnailToContainer: unknown;
+  container: unknown;
+  width: unknown;
+  clearSearchHighlights: unknown;
+  destroy: unknown;
+}`
+  `PptxZipLimits {
+  maxEntries: unknown;
+  maxEntryUncompressedBytes: unknown;
+  maxTotalUncompressedBytes: unknown;
+  maxMediaBytes: unknown;
+  maxConcurrency: unknown;
+}`
+
 - **`components-viewers-spreadsheet-viewer-spreadsheet-loader-contracts`** — Supporting data types and helpers for this component family.
   `clearSheetJsCache(): unknown`
   `loadSheetJsCached(): unknown`
@@ -27464,8 +28211,9 @@ support (`highlights`, `activeHighlightId`, `scrollToAnchor()`, the `lr-highligh
 section above for the full write-up of shared behavior.
 
 **Properties:** `content: string = ''`, `tabSize: number = 4` (attribute `tab-size`) — the same
-finite-integer-guarded leading-indentation expansion used by `<lr-markdown>`; values outside 1–32
-or non-finite values fall back to `4`, independently of rendered code's
+finite-integer-guarded leading-indentation expansion used by `<lr-markdown>`; finite values are
+clamped to `[1, 32]` (`0` becomes `1`, `33` becomes `32`), and only non-finite values (`NaN`,
+`Infinity`) fall back to `4`, independently of rendered code's
 `--lr-code-block-tab-size`; `marked: LyraMarkedParser | undefined` (readonly, no attribute) — this
 instance's isolated peer-neutral configurable parser; `htmlMode: 'sanitize' | 'escape' | 'trusted' =
 'sanitize'` (attribute `html-mode`), `gfm: boolean = true`, `linkTarget: string | null = '_blank'` (attribute
@@ -28204,13 +28952,16 @@ Plus shared tokens — `--lr-space-xs/-s/-m`, `--lr-radius`,
   conversation-id="sess_123"
   label="Q3 roadmap planning"
   excerpt="Let's revisit the timeline for the launch…"
-  .timestamp=${session.updatedAt}
-  ?active=${session.id === currentSessionId}
-  @lr-select=${(e) => openSession(e.detail.conversationId)}
-  @lr-rename=${(e) => renameSession(e.detail.conversationId, e.detail.label)}
 >
   <button slot="actions" aria-label="Delete conversation">✕</button>
 </lr-conversation-item>
+<script type="module">
+  const item = document.querySelector("lr-conversation-item");
+  item.timestamp = session.updatedAt;
+  item.active = session.id === currentSessionId;
+  item.addEventListener("lr-select", (e) => openSession(e.detail.conversationId));
+  item.addEventListener("lr-rename", (e) => renameSession(e.detail.conversationId, e.detail.label));
+</script>
 ```
 
 `role="button"` lives on `[part="select-button"]`, so the row has
@@ -28459,19 +29210,18 @@ shared tokens — `--lr-space-xs/-s`, `--lr-color-border/-surface/-brand/-brand-
 **Optional peer deps:** none.
 
 ```html
-<lr-model-select
-  provider="openai"
-  .catalog=${[
-    { id: 'gpt-4o', label: 'GPT-4o', icon: '✦' },
-    { id: 'gpt-4o-mini', label: 'GPT-4o mini' },
-  ]}
-  value="gpt-4o"
-  placeholder="Choose a model…"
-  @lr-change=${(e) => setModel(e.detail.value, e.detail.inCatalog)}
-></lr-model-select>
+<lr-model-select provider="openai" value="gpt-4o" placeholder="Choose a model…"></lr-model-select>
 
 <!-- No fixed catalog yet: falls back to free-text entry -->
 <lr-model-select provider="ollama" placeholder="Type a model id…" allow-custom></lr-model-select>
+<script type="module">
+  const select = document.querySelector("lr-model-select");
+  select.catalog = [
+    { id: "gpt-4o", label: "GPT-4o", icon: "✦" },
+    { id: "gpt-4o-mini", label: "GPT-4o mini" },
+  ];
+  select.addEventListener("lr-change", (e) => setModel(e.detail.value, e.detail.inCatalog));
+</script>
 ```
 
 **Known gotchas:**
@@ -29049,15 +29799,15 @@ selector label), `temperature-row`, `temperature-label`, `temperature-value`
 internally (both imported unconditionally as side effects, not optional).
 
 ```html
-<lr-model-settings-panel
-  provider="OpenAI"
-  .catalog=${['gpt-4o', 'gpt-4o-mini', 'gpt-4.1']}
-  model="gpt-4o"
-  temperature="0.7"
-  @lr-change=${(e) => console.log(e.detail)}
-></lr-model-settings-panel>
+<lr-model-settings-panel provider="OpenAI" model="gpt-4o" temperature="0.7"></lr-model-settings-panel>
 
-<lr-model-settings-panel layout="compact" .catalog=${catalog}></lr-model-settings-panel>
+<lr-model-settings-panel layout="compact"></lr-model-settings-panel>
+<script type="module">
+  const [panel, compactPanel] = document.querySelectorAll("lr-model-settings-panel");
+  panel.catalog = ["gpt-4o", "gpt-4o-mini", "gpt-4.1"];
+  panel.addEventListener("lr-change", (e) => console.log(e.detail));
+  compactPanel.catalog = catalog;
+</script>
 ```
 
 The internal `lr-slider` renders with its own value readout suppressed (`.showValue=${false}`);
@@ -29483,13 +30233,18 @@ component's existing requirement of a height-bounded parent, exactly as slotted
 inline style) still wins over the built-in one.
 
 ```html
-<lr-chat-viewport unread-start-index="12" @lr-follow-change=${(e) => console.log(e.detail.following)}>
+<lr-chat-viewport unread-start-index="12">
   <lr-chat-message message-role="user">…</lr-chat-message>
   <lr-chat-message message-role="assistant" status="streaming">
-    <lr-streaming-text streaming .content=${partial}></lr-streaming-text>
+    <lr-streaming-text streaming></lr-streaming-text>
   </lr-chat-message>
 </lr-chat-viewport>
 <lr-chat-composer status="streaming"></lr-chat-composer>
+<script type="module">
+  const viewport = document.querySelector("lr-chat-viewport");
+  viewport.querySelector("lr-streaming-text").content = partial;
+  viewport.addEventListener("lr-follow-change", (e) => console.log(e.detail.following));
+</script>
 ```
 
 ## `lr-suggestion-chips`
@@ -29537,9 +30292,14 @@ Enter/Space activate. Renders inside an internal `lr-scroller` (`orientation="ho
 `hide-scrollbar`) unless `wrap` is set.
 
 ```html
-<lr-suggestion-chips .suggestions=${followUps}
-  @lr-suggestion-select=${(e) => (composer.value = e.detail.label)}></lr-suggestion-chips>
+<lr-suggestion-chips></lr-suggestion-chips>
 <lr-chat-composer></lr-chat-composer>
+<script type="module">
+  const chips = document.querySelector("lr-suggestion-chips");
+  const composer = document.querySelector("lr-chat-composer");
+  chips.suggestions = followUps;
+  chips.addEventListener("lr-suggestion-select", (e) => (composer.value = e.detail.label));
+</script>
 ```
 
 ## `lr-thread-list`
@@ -29722,14 +30482,14 @@ short one, and falls back to exactly `24rem` in an auto-height container.
 style the pinned band with `lr-thread-list::part(group-sticky)`.
 
 ```html
-<lr-thread-list
-  searchable
-  sticky-groups
-  .threads=${threads}
-  active-conversation-id=${activeThreadId}
-  .rowActions=${['pin', 'archive', 'delete']}
-  @lr-select=${(e) => openThread(e.detail.conversationId)}
-></lr-thread-list>
+<lr-thread-list searchable sticky-groups></lr-thread-list>
+<script type="module">
+  const list = document.querySelector("lr-thread-list");
+  list.threads = threads;
+  list.activeConversationId = activeThreadId;
+  list.rowActions = ["pin", "archive", "delete"];
+  list.addEventListener("lr-select", (e) => openThread(e.detail.conversationId));
+</script>
 ```
 
 Composed with `lr-multi-split` (or `lr-app-rail` + `lr-responsive-panel`): thread-list in the start
@@ -29778,8 +30538,12 @@ assigned to `animation-duration` alone. The spinner stops outright under
 `prefers-reduced-motion: reduce`.
 
 ```html
-<lr-checkpoint checkpoint-id="ck_18" label="Before refactor" .timestamp=${t}
-  @lr-restore=${(e) => restoreTo(e.detail.checkpointId)}></lr-checkpoint>
+<lr-checkpoint checkpoint-id="ck_18" label="Before refactor"></lr-checkpoint>
+<script type="module">
+  const checkpoint = document.querySelector("lr-checkpoint");
+  checkpoint.timestamp = t;
+  checkpoint.addEventListener("lr-restore", (e) => restoreTo(e.detail.checkpointId));
+</script>
 ```
 
 ## `lr-usage-badge`
@@ -29822,8 +30586,11 @@ describable), `summary`, `tokens-in`, `tokens-out`, `cost`, `latency`, `tooltip`
     cost-text="$0.012"
     latency-ms="2350"
   ></lr-usage-badge>
-  <lr-markdown .content="${answer}"></lr-markdown>
+  <lr-markdown></lr-markdown>
 </lr-chat-message>
+<script type="module">
+  document.querySelector("lr-chat-message lr-markdown").content = answer;
+</script>
 ```
 
 ## `lr-widget-renderer`
@@ -29857,9 +30624,9 @@ readonly slot?: string; readonly actionId?: string; readonly payload?: unknown }
 - `LyraWidgetDocument { readonly version: '2'; readonly root: LyraWidgetNode }` — the sole versioned tree source.
 - `createWidgetDocument(root: LyraWidgetNode): LyraWidgetDocument` — creates an immediate frozen
   version-two snapshot for former unversioned tree assignments. Traversal uses the renderer's depth,
-  node, and per-node prop ceilings; malformed, cyclic, duplicate-id, or hostile structure throws
-  `TypeError`. Node records, child arrays, and prop records are copied and frozen, while opaque prop
-  values and action payloads intentionally retain caller identity.
+  node, per-node prop, and per-string length ceilings; malformed, cyclic, duplicate-id, or hostile
+  structure throws `TypeError`. Node records, child arrays, and prop records are copied and frozen,
+  while opaque prop values and action payloads intentionally retain caller identity.
 
 The package root and the normal `widget-renderer.js` registration entry expose the renderer
 `LyraWidgetRenderer`/`LyraWidgetRendererEventMap` together with the complete stable authoring
@@ -30126,15 +30893,18 @@ stale-value row), `option-preview` (a pointer-only per-row preview icon, `tabind
 trigger), `expand-icon`, `empty`, `hint`, `error`.
 
 ```html
-<lr-voice-picker provider="elevenlabs" .catalog=${voices} allow-custom
-  @lr-change=${(e) => setVoice(e.detail.value)}
-  @lr-preview-request=${(e) => {
+<lr-voice-picker provider="elevenlabs" allow-custom></lr-voice-picker>
+<script type="module">
+  const picker = document.querySelector("lr-voice-picker");
+  picker.catalog = voices;
+  picker.addEventListener("lr-change", (e) => setVoice(e.detail.value));
+  picker.addEventListener("lr-preview-request", (e) => {
     if (!e.detail.previewUrl) {
       e.preventDefault();
       playSample(e.detail.voiceId);
     }
-  }}
-></lr-voice-picker>
+  });
+</script>
 ```
 
 **Known gotchas:**
@@ -30280,6 +31050,26 @@ optional-peer fallback.
 Every public data/value property is controlled: forwarded child intents bubble without mutating
 `messages`, `composerValue`, selections, run state, or persistence-owned data inside the shell.
 
+**Only the transcript scrolls.** `[part='base']` is a three-row grid — header, conversation,
+composer — and only the middle row can shrink, so the composed `lr-chat-viewport` owns the
+scrolling and the chrome rows stay put at their content size. The trade: give the workspace less
+block-size than the chrome needs and the conversation row collapses to zero first, after which the
+header or composer is clipped with no scrollbar. That takes unusually large slotted chrome — a very
+tall `header-actions` toolbar, or a `composer` replacement much taller than the built-in one — and
+the region that supplied it caps and scrolls itself through the public parts:
+
+```css
+lr-agent-workspace::part(header) {
+  max-block-size: 4rem;
+  overflow: auto;
+}
+```
+
+The same applies to `::part(composer)`. Both declarations are needed: the cap keeps the grid track
+inside the workspace, and `overflow` makes the capped region scrollable instead of spilling. No
+component-owned custom property duplicates this, because a `::part()` rule from your tree already
+wins over the shadow stylesheet regardless of specificity.
+
 ## `lr-message-parts`
 
 Ordered renderer for provider-neutral `MessagePart[]`: text, reasoning, tool call/result, citation,
@@ -30341,7 +31131,8 @@ import "@aceshooting/lyra-ui/components/conversation/message-parts/message-parts
 - `lr-copy` event — Passthrough from rendered JSON content.
 - `lr-highlight-activate` event — Passthrough from rendered Markdown.
 - `lr-link-click` event — Passthrough from rendered Markdown.
-- `lr-preview-request` event — Cancelable passthrough from a rendered attachment.
+- `lr-preview-request` event — Passthrough from a rendered attachment. Not cancelable as of 10.0.0:
+  `<lr-attachment-chip>` dropped the flag, since it owns no preview default action to veto.
 - `lr-remove` event — Passthrough from a rendered attachment.
 - `lr-render-error` event — Passthrough from rendered Markdown, tool-result, or widget content.
 - `lr-retry` event — Passthrough from a rendered attachment.
@@ -30590,6 +31381,7 @@ These named interfaces and helper signatures are available to typed integrations
 - **`components-conversation-code-block-code-loader-contracts`** — Supporting data types and helpers for this component family.
   `loadShikiHighlighter(): unknown`
   `loadShikiLanguage(/* public names: hl, lang */): unknown`
+  `shikiHasLoadedLanguage(/* public names: hl, lang */): unknown`
 
 - **`components-conversation-code-block-shiki-types-contracts`** — Supporting data types and helpers for this component family.
   `loadShikiHighlighterCore(/* public names: languages */): unknown`
@@ -30940,11 +31732,15 @@ referenced: `--lr-color-text-quiet`, `--lr-color-surface`, `--lr-color-border`,
   summary="Searching web…"
   duration-ms="820"
   call-id="call_123"
-  @lr-tool-call-chip-select=${(e) => openDetail(e.detail.callId)}
 >
   <pre slot="icon" style="display:none"></pre>
   <code>{"query": "lyra ui components"}</code>
 </lr-tool-call-chip>
+<script type="module">
+  document
+    .querySelector("lr-tool-call-chip")
+    .addEventListener("lr-tool-call-chip-select", (e) => openDetail(e.detail.callId));
+</script>
 ```
 
 The default slot's tooltip is positioned with the same `internal/positioner.js` `place()` helper
@@ -31036,12 +31832,13 @@ of course pull in whatever they need (a charting library, a markdown renderer),
 the lazy `load()` path in the registry exists for.
 
 ```html
-<lr-tool-result-view
-  tool-name="get_weather"
-  .result=${{ tempC: 21, condition: 'cloudy' }}
-  .args=${{ city: 'Brussels' }}
-  @lr-render-error=${(e) => console.warn('renderer failed', e.detail)}
-></lr-tool-result-view>
+<lr-tool-result-view tool-name="get_weather"></lr-tool-result-view>
+<script type="module">
+  const view = document.querySelector("lr-tool-result-view");
+  view.result = { tempC: 21, condition: "cloudy" };
+  view.args = { city: "Brussels" };
+  view.addEventListener("lr-render-error", (e) => console.warn("renderer failed", e.detail));
+</script>
 ```
 
 ### `registerToolRenderer()` and the tool-renderer registry (`registry.ts`)
@@ -31255,20 +32052,22 @@ tokens `--lr-color-surface/-border/-text-quiet/-brand/-brand-quiet/-success/-suc
 **Optional peer deps:** none.
 
 ```html
-<lr-tool-result-dialog
-  tool-name="run_query"
-  status="success"
-  duration-ms="1240"
-  ?open=${dialogOpen}
-  @lr-close=${(e) => (dialogOpen = false)}
-  @lr-maximize-change=${(e) => console.log('maximized:', e.detail.maximized)}
->
+<lr-tool-result-dialog tool-name="run_query" status="success" duration-ms="1240">
   <lr-tab-group slot="body">
     <div slot="preview" label="Preview">…</div>
-    <div slot="json" label="JSON"><lr-json-viewer .data=${result}></lr-json-viewer></div>
+    <div slot="json" label="JSON"><lr-json-viewer></lr-json-viewer></div>
   </lr-tab-group>
   <button slot="footer">Rerun</button>
 </lr-tool-result-dialog>
+<script type="module">
+  const dialog = document.querySelector("lr-tool-result-dialog");
+  dialog.querySelector("lr-json-viewer").data = result;
+  dialog.open = true;
+  dialog.addEventListener("lr-close", () => (dialog.open = false));
+  dialog.addEventListener("lr-maximize-change", (e) =>
+    console.log("maximized:", e.detail.maximized)
+  );
+</script>
 ```
 
 While open, `[part="panel"]` takes `role="dialog"` + `aria-modal="true"` with `aria-labelledby`
@@ -31400,23 +32199,25 @@ assigned elements.
 dependencies of this package imported directly, not optional peers.
 
 ```html
-<lr-tool-select-dialog
-  label="Select tools"
-  .tools=${[
-    { id: 'search', name: 'Web search', category: 'Research' },
-    { id: 'python', name: 'Python', category: 'Code', description: 'Run sandboxed Python' },
-    { id: 'admin', name: 'Admin console', disabled: true, disabledReason: 'Requires admin approval' },
-  ]}
-  .selectedToolIds=${enabledToolIds}
-  ?use-defaults=${usingDefaults}
-  ?open=${dialogOpen}
-  @lr-change=${(e) => updateTools(e.detail.selectedToolIds, e.detail.useDefaults)}
-  @lr-close=${() => (dialogOpen = false)}
->
-  <button slot="footer" @click=${(e) => e.target.closest('lr-tool-select-dialog').close('done')}>
-    Done
-  </button>
+<lr-tool-select-dialog label="Select tools">
+  <button slot="footer" id="done-btn">Done</button>
 </lr-tool-select-dialog>
+<script type="module">
+  const dialog = document.querySelector("lr-tool-select-dialog");
+  dialog.tools = [
+    { id: "search", name: "Web search", category: "Research" },
+    { id: "python", name: "Python", category: "Code", description: "Run sandboxed Python" },
+    { id: "admin", name: "Admin console", disabled: true, disabledReason: "Requires admin approval" },
+  ];
+  dialog.selectedToolIds = enabledToolIds;
+  dialog.useDefaults = usingDefaults;
+  dialog.open = true;
+  dialog.addEventListener("lr-change", (e) =>
+    updateTools(e.detail.selectedToolIds, e.detail.useDefaults)
+  );
+  dialog.addEventListener("lr-close", () => (dialog.open = false));
+  dialog.querySelector("#done-btn").addEventListener("click", () => dialog.close("done"));
+</script>
 ```
 
 `useDefaults` is a single top-level switch: while `true`, every per-tool checkbox renders disabled
@@ -31775,15 +32576,14 @@ other text-entry surface in the library provides), plus shared tokens
 package, not an optional peer.
 
 ```html
-<lr-tool-approval-dialog
-  tool-name="send_email"
-  .args=${{ to: 'ops@example.com', subject: 'Deploy finished' }}
-  @lr-approve=${(e) => runTool(e.detail.args)}
-  @lr-deny=${() => console.log('denied')}
-  @lr-close=${(e) => console.log('closed:', e.detail)}
-></lr-tool-approval-dialog>
+<lr-tool-approval-dialog tool-name="send_email"></lr-tool-approval-dialog>
 <script type="module">
-  document.querySelector('lr-tool-approval-dialog').open = true;
+  const dialog = document.querySelector("lr-tool-approval-dialog");
+  dialog.args = { to: "ops@example.com", subject: "Deploy finished" };
+  dialog.addEventListener("lr-approve", (e) => runTool(e.detail.args));
+  dialog.addEventListener("lr-deny", () => console.log("denied"));
+  dialog.addEventListener("lr-close", (e) => console.log("closed:", e.detail));
+  dialog.open = true;
 </script>
 ```
 
@@ -32001,20 +32801,22 @@ form: `--lr-space-l/-xs/-s`, `--lr-color-border`, `--lr-radius`, `--lr-color-sur
 dependencies of this package imported directly, not optional peers.
 
 ```html
-<lr-tool-param-form
-  .schema=${{
-    type: 'object',
+<lr-tool-param-form></lr-tool-param-form>
+<script type="module">
+  const form = document.querySelector("lr-tool-param-form");
+  form.schema = {
+    type: "object",
     properties: {
-      title: { type: 'string', title: 'Title' },
-      attendees: { type: 'string', enum: ['team', 'everyone'], default: 'team' },
-      allDay: { type: 'boolean', title: 'All day' },
+      title: { type: "string", title: "Title" },
+      attendees: { type: "string", enum: ["team", "everyone"], default: "team" },
+      allDay: { type: "boolean", title: "All day" },
     },
-    required: ['title'],
-  }}
-  .value=${draftArgs}
-  @lr-input=${(e) => (draftArgs = e.detail.value)}
-  @lr-validity-change=${(e) => (formIsValid = e.detail.valid)}
-></lr-tool-param-form>
+    required: ["title"],
+  };
+  form.value = draftArgs;
+  form.addEventListener("lr-input", (e) => (draftArgs = e.detail.value));
+  form.addEventListener("lr-validity-change", (e) => (formIsValid = e.detail.valid));
+</script>
 ```
 
 This component owns no Submit/Cancel/Approve chrome — a consumer composes it inside their own dialog
@@ -32406,7 +33208,9 @@ default the component creates a plain-text `Blob`/object URL and activates a syn
 `<a download>`; `preventDefault()` suppresses that built-in download so the host can substitute
 server-side or other handling),
 `lr-follow-change` (`detail: { following }`), `lr-search-change` (`detail: { query, matchCount,
-activeIndex }`), `lr-highlight-activate` (`detail: { highlightId }`), and `lr-text-select` (`detail: {
+matchCountExact, activeIndex }`; `matchCountExact` is `false` once a search hits the 10,000-match
+ceiling, marking `matchCount` as a lower bound rather than an exact total),
+`lr-highlight-activate` (`detail: { highlightId }`), and `lr-text-select` (`detail: {
 text, anchor, rects }`).
 
 **CSS parts:** `base`, `toolbar` (only rendered when copy/download are enabled), `copy-button`,
@@ -32504,9 +33308,11 @@ columns. Consumes the same `LyraSpan[]` as `<lr-span-waterfall>`.
 under `lr-span-waterfall` above (exported from `trace-tree/span.ts`); hierarchy comes from
 `parentId`, and a span whose `parentId` is missing or doesn't resolve within the same array renders
 as a root rather than being dropped. `activeSpanId: string | null = null`
-(attribute `active-span-id`), `label: string = ''`, `showTokens: boolean = false` (attribute
+(attribute `active-span-id`), `label?: string`, `showTokens: boolean = false` (attribute
 `show-tokens`) — surfaces `tokensIn`/`tokensOut`, `showCost: boolean = false` (attribute
 `show-cost`) — surfaces `costText`, and `hideBars: boolean = false` (attribute `hide-bars`).
+`label` is an optional accessible-name override for the `role="tree"` element: omission localizes
+the default, and any supplied string — including `''` — is rendered verbatim.
 Token counts render only when finite and non-negative; invalid metrics are omitted rather than
 reaching `Intl.NumberFormat`. A row's accessible name includes its optional `detail` text as well
 as its name/status/metrics, and updates when the supplied span data changes. Every trace view uses
@@ -32828,9 +33634,13 @@ repainting everything else that reads them.
 
 ```html
 <lr-tool-call-chip status="pending"></lr-tool-call-chip>
-<lr-confirm-bar tool-name="run_shell" .args=${args}
-  @lr-approve=${(e) => run(e.detail.args)} @lr-deny=${() => cancel()}
-></lr-confirm-bar>
+<lr-confirm-bar tool-name="run_shell"></lr-confirm-bar>
+<script type="module">
+  const bar = document.querySelector("lr-confirm-bar");
+  bar.args = args;
+  bar.addEventListener("lr-approve", (e) => run(e.detail.args));
+  bar.addEventListener("lr-deny", () => cancel());
+</script>
 ```
 
 An `lr-approve`/`lr-deny` listener that needs to await its own async work before finalizing calls
@@ -32892,9 +33702,13 @@ phase write queued while detached.
 viewport's aspect ratio.
 
 ```html
-<lr-browser-frame phase="streaming" url="https://example.com" .pings=${pings}
-  @lr-take-over=${(e) => setController(e.detail.controller)} @lr-stop=${() => stopSession()}
-></lr-browser-frame>
+<lr-browser-frame phase="streaming" url="https://example.com"></lr-browser-frame>
+<script type="module">
+  const frame = document.querySelector("lr-browser-frame");
+  frame.pings = pings;
+  frame.addEventListener("lr-take-over", (e) => setController(e.detail.controller));
+  frame.addEventListener("lr-stop", () => stopSession());
+</script>
 ```
 
 **Additional API surface:**
@@ -32968,11 +33782,17 @@ ancestor. They exist because `::part(view-button)[aria-pressed='true']` is inval
 library-wide brand tokens as the only prior lever.
 
 ```html
-<lr-artifact-panel label="report.md" kind="document" .versions=${versions}
-  @lr-restore=${(e) => restoreVersion(e.detail.versionId)}>
-  <lr-markdown .content=${markdown}></lr-markdown>
-  <lr-code-block slot="code" language="markdown" .code=${markdown}></lr-code-block>
+<lr-artifact-panel label="report.md" kind="document">
+  <lr-markdown id="preview"></lr-markdown>
+  <lr-code-block slot="code" id="code" language="markdown"></lr-code-block>
 </lr-artifact-panel>
+<script type="module">
+  const panel = document.querySelector("lr-artifact-panel");
+  panel.versions = versions;
+  panel.querySelector("#preview").content = markdown;
+  panel.querySelector("#code").code = markdown;
+  panel.addEventListener("lr-restore", (e) => restoreVersion(e.detail.versionId));
+</script>
 ```
 
 ## `lr-agent-run`
@@ -33081,7 +33901,9 @@ hierarchical trace tree from one shared `spans` array.
   (`'agent' | 'llm' | 'tool' | 'retriever' | 'embedding' | 'other'`). Empty shows every kind;
   pre-settable (e.g. to hide `retriever`/`embedding` by default) and readable back after
   `lr-span-visibility-change`
-- `label: string = ''` — forwarded to the composed `lr-trace-tree`
+- `label?: string` — forwarded to the composed `lr-trace-tree`. Omission leaves that tree's own
+  `label` unset so it localizes its own default; any supplied string (including `''`) is
+  forwarded verbatim
 - `showTokens: boolean = false` (attribute `show-tokens`), `showCost: boolean = false` (attribute
   `show-cost`), `showBars: boolean = true` (attribute `show-bars`, renamed from `hideBars` in
   9.0.0 to match the positive polarity of its two siblings above — default inverted so the
@@ -33610,7 +34432,7 @@ persistence.
 `versions: readonly PromptStudioVersion[] = []` is a property-only host-controlled input;
 empty/blank message and version ids are omitted and later duplicates use deterministic first-wins
 identity before rendering, editing, focus, selection, and events;
-`selectedVersionId: string = ''` (attribute `selected-version-id`); `label: string = ''`;
+`selectedVersionId: string | null = null` (attribute `selected-version-id`); `label: string = ''`;
 `heading: string = ''` — visible toolbar heading, falling back to the localized Prompt Studio
 label when unset;
 `running: boolean = false`, `disabled: boolean = false`, and `reorderable: boolean = false`
@@ -33677,7 +34499,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,
@@ -34208,6 +35031,44 @@ These named interfaces and helper signatures are available to typed integrations
 
 # Retrieval, knowledge graph & grounding (`components/retrieval/`)
 
+## Breaking changes in 10.0.0
+
+`lr-entity-card`, `lr-entity-chip` and `lr-neighbor-list` no longer emit `lr-entity-activate`. The
+canonical name for that gesture is `lr-entity-select` (`detail: { entityId }`), fired from the same
+gesture with the same detail — only the second spelling is gone. It is removed outright rather than
+kept as a dual-emitting alias, because the library has no released consumers and an alias is a
+permanent tax paid to protect users who do not exist. Rename the listener; nothing else changes.
+
+Two composites narrow with them. `lr-entity-dossier` surfaces its embedded entity card's and
+neighbor list's gesture as `lr-entity-select` only, and `lr-provenance-panel` does the same for its
+embedded entity chip. On both, `lr-entity-activate` now reaches a host only from the embedded
+community card or relationship path strip, which is also the only source of the richer
+`{ entityId, occurrenceIndex? }` detail — so on these two elements the names now carry different
+shapes rather than being two spellings of one event.
+
+`lr-community-card` and `lr-path-strip` keep `lr-entity-activate` unchanged. It is their only name
+and never was an alias, so do **not** rename those listeners.
+
+`lr-rag-eval-dashboard` no longer emits `lr-run-select`; listen for `lr-run-change`
+(`detail: { run }`, unchanged). Same removal, same reason.
+
+`lr-knowledge-graph-explorer`'s `lr-search-change` detail is now exactly
+`{ query, matchCount, matchCountExact }`. The old `searchQuery` member is replaced by the canonical
+`query` rather than carried beside it, so the event finally has the `LyraSearchChangeDetail` shape
+the rest of the library's search emitters use — read `e.detail.query`. The detail deliberately has no
+`activeIndex` (this is a live node filter, not a cursor-based search) and `matchCountExact` is always
+`true`, since that filter has no truncating ceiling. The `searchQuery` **property** is a different
+member and is unaffected: the component still applies the query to it before emitting, so reassigning
+it from the handler stays a no-op.
+
+Also corrected in 10.0.0 — not breaking, but visible. A chip with no `entity-id` renders its button
+disabled, and now looks it: `lr-entity-chip` used to paint that state pixel-identical to a working
+chip — full opacity, a hand cursor, complete hover and press feedback for a control that cannot emit
+anything — and now dims to `--lr-opacity-disabled` with a `not-allowed` cursor and no pointer
+response. `lr-embedding-explorer`'s selected point has a focus ring again. And
+`lr-knowledge-graph-explorer` no longer announces on mount: a preset `search-query` used to fire its
+live region before any user action.
+
 ## Breaking changes in 9.0.0
 
 `lr-graph`'s exported types `GraphLayout`, `GraphRenderer`, `GraphSelectionMode`, `GraphPickKind`, and
@@ -34659,7 +35520,7 @@ only that row's decorative swatch opacity. Also reads `--lr-graph-cat-1` through
 
 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:**
@@ -34684,7 +35545,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).
@@ -34717,7 +35578,7 @@ from tokens.
   };
   document
     .getElementById("card")
-    .addEventListener("lr-entity-activate", (e) =>
+    .addEventListener("lr-entity-select", (e) =>
       graph.focusNode(e.detail.entityId)
     );
 </script>
@@ -34754,7 +35615,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
@@ -34802,7 +35663,7 @@ graph data) and never mutates a graph.
 - `label: string = ''` — fallback name for the stable group. A non-empty host `aria-label` makes
   the host the sole overall owner; an explicitly empty host label stays empty on the group
 
-**Events:** `lr-entity-activate` (`detail: { entityId }`, a row's node button was activated),
+**Events:** `lr-entity-select` (`detail: { entityId }`, a row's node button was activated),
 `lr-node-expand` (`detail: { nodeId }`, a row's expand button was activated — deliberately the same
 name and detail shape as `lr-graph`'s own event, so one host handler serves both).
 
@@ -35173,8 +36034,10 @@ chip` row, one `lr-path-strip` per relationship, `lr-community-card`, `lr-chunk-
 **Events:** `lr-toggle` (`detail: { section, expanded }`, a section header was toggled —
 `section` is `'entities' | 'relationships' | 'communities' | 'chunks'`). Because the panel is a
 conduit, every affordance it renders also reaches a listener on the panel itself, and all are
-part of its typed event map: `lr-entity-activate` (`detail: { entityId, occurrenceIndex? }`, from an entity chip, community
-card member, or path-strip node), `lr-entity-open` (`detail: { entityId }`, an entity chip double-click or
+part of its typed event map: `lr-entity-select` (`detail: { entityId }`, from an entity chip),
+`lr-entity-activate` (`detail: { entityId, occurrenceIndex? }`, from a community card member or
+path-strip node — the only name either one emits, and the only one carrying `occurrenceIndex`),
+`lr-entity-open` (`detail: { entityId }`, an entity chip double-click or
 Space), `lr-drill` (`detail: { communityId }`, a community card's title, drill button, or overflow chip), and
 `lr-relation-activate` (`detail: { relation, sourceNodeId?, targetNodeId?, occurrenceIndex }`, a relationship path-strip
 edge), plus `lr-chunk-open` (`detail: { chunkId, sourceId, anchor? }`) and `lr-expand`
@@ -35569,7 +36432,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'
@@ -35864,9 +36730,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`),
@@ -36470,7 +37341,7 @@ duplicates are omitted first-wins before metric fallback, slice derivation/filte
 history, counts, rendering, or actions.
 
 **Events:** `lr-metric-change` (`{ metricId }`), `lr-slice-change` (`{ slice }`), and
-`lr-run-select` (`{ run }`). All are controlled intents; the component does not mutate the
+`lr-run-change` (`{ run }`). All are controlled intents; the component does not mutate the
 corresponding selection properties.
 
 **CSS parts:** `base`, `heading`, `slices`, `slice`, `slice-selected`, `metrics`, `metric`,