@aceshooting/lyra-ui 21.0.0 → 21.1.0

package/llms-full.txt

@@ -12,7 +12,7 @@ Read it end to end only if you genuinely need everything. Otherwise:
 
 | To… | Read |
 |---|---|
-| use one component | `llms/components/<tag>.md` (path derived from the tag; self-contained) |
+| use one component | `llms/components/<tag>.md` (path derived from the tag; a sibling-documented tag points to its primary file) |
 | find the right component | `llms/index.md` (every tag, its import path, one-line purpose) |
 | get library-wide behavior right | `llms/shared.md` (status, imports/autoloading, events, forms, theming/styles, i18n/RTL, TS/frameworks, SSR, utilities, AI types) |
 | theme it | `llms/tokens.md` |
@@ -28,9 +28,11 @@ a sibling `.class.js` exports a class without registering it.
 ## Contents
 
 This file is the concatenation of the per-family sources in `llms/`. When only one component is
-in question, read `llms/components/<tag>.md` instead — it is the same text plus its import path,
-and costs a few hundred tokens instead of the whole catalog. `llms/index.md` maps every tag to its
-family and entry point.
+in question, read `llms/components/<tag>.md` instead — for a tag documented on its own, that file
+holds the same text plus its import path; for a tag documented together with siblings, it holds
+the generated facts (import path, status, peers, and so on) plus a pointer to the primary
+sibling's file for the shared prose. Either way it costs a few hundred tokens instead of the
+whole catalog. `llms/index.md` maps every tag to its family and entry point.
 
 - **Foundation** — base class, form association, events, i18n, theming, TypeScript, frameworks, SSR, packaging (`llms/shared.md`)
 - **Form controls & inputs** — 31 tags in `components/forms/`
@@ -82,15 +84,40 @@ customary M+1 warning period — `lr-usage-badge`'s `compact`, `lr-chart`'s `hor
 a mechanical migration listed in the 9.0.0 changelog entry and in `migration.md`. From 9.0.0 onward
 the M+2 rule applies as written; treat the above as a documented exception, not a precedent.
 
+Deprecation records also cover three things that are not a single member. Deprecated **slot
+content** is a kind of content inside a slot that stays supported (for example, content other than
+items in a menu's default slot); the slot's own description says which content is deprecated.
+Deprecated **package entry points** (an import path) and deprecated **exported types** are listed
+under "Deprecated package exports" at the end of `llms/index.md`; a deprecated type also carries
+`@deprecated` in its declaration, so editors strike it through. Each component's own deprecations
+are listed in its `llms/components/<tag>.md` header and in `custom-elements.json` (the declaration's
+`deprecations`, plus a `deprecation` on each deprecated member). These records are the complete
+list of deprecated APIs; audit an upgrade against them, not against console output.
+
+**Development warnings.** Some deprecations also log a development-mode `console.warn` naming the
+element, the deprecated API, and its replacement. A warning only ever fires for usage a component
+can observe cheaply and exactly — setting a deprecated property or attribute, connecting a
+deprecated tag, or vetoing through a deprecated alias event — and **not every deprecated API
+warns**: many deprecations have no runtime warning, among them `lr-icon`'s `auto-width`,
+`lr-stat`'s default-slot icon, `lr-menu`'s non-item default-slot content, the `lr-before-*` alias
+events of `lr-chart`, `lr-box-plot`, `lr-graph-legend` and `lr-graph-query-builder`, and
+`lr-command-palette`'s `lr-open` alias event, and deprecated CSS parts, custom properties, and
+custom states are styling hooks a component cannot observe, so they never warn. A silent console
+is therefore not evidence that an application uses no deprecated API. Where a warning exists, it
+fires once per page for each element name and deprecated API, and only when Lit runs its
+development build; production builds never warn. The deprecated form keeps working either
+way, and moving to the replacement removes the warning. A test suite that fails on console output
+while deliberately exercising a deprecated form can pre-seed Lit's development-mode
+`globalThis.litIssuedWarnings` set, before the element renders, with the key
+`lyra-deprecated:<tag>:<kind>:<name>` — `<kind>` and `<name>` as in the deprecation record.
+
 ### Release history and upgrade notes
 
-`since` records when a tag first appeared; it is not a history of later additions, fixes, or
-breaking changes. For every release after 9.0.0 — including minor and patch releases — read the
-package's shipped [CHANGELOG.md](./CHANGELOG.md) before upgrading. Family-wide breaking-change
-summaries sit at the start of the applicable authored `llms/<family>.md` file; each generated
-`llms/components/<tag>.md` header links that family summary when one exists. Component-specific
-version notes remain in the component's own section. `llms/migration.md` is narrower: it covers
-`wa-*`/`sl-*` renames and compatibility decisions, not Lyra release history.
+`since` records when a tag first appeared, not later changes. Before upgrading, read the
+package's [CHANGELOG.md](./CHANGELOG.md) (every release, including minor and patch).
+Family-wide breaking-change summaries open each authored `llms/<family>.md`, and each generated
+`llms/components/<tag>.md` header links its family summary. `llms/migration.md` covers only
+`wa-*`/`sl-*` renames, not Lyra release history.
 
 The major-version landmarks after 9.0.0 are:
 
@@ -2153,17 +2180,21 @@ override takes precedence over either page-level choice.
 
 To keep `<html lang>`/`dir` in step with `setLyraLocale()` — which everything _outside_ this library
 reads, from `:lang()` rules to spellcheck to a screen reader's pronunciation — use
-`bridgeLyraLocale()` from `@aceshooting/lyra-ui/utilities/localization.js` (see
+`bridgeLyraLocale()` from `@aceshooting/lyra-ui/localization.js` (see
 [Shared helpers](#shared-helpers-utilities)).
 
 The side-effect-free `@aceshooting/lyra-ui/localization.js` entry exports
 `registerLyraLocale`, `setLyraLocale`, `getLyraLocale`, `getLyraLocaleDirection`,
 `getRegisteredLyraLocales`, `getRegisteredLyraLocaleKeys`, `subscribeLyraLocaleRegistry`,
-`resolveLyraLocale`, `resolveLyraDirection`, `resolveLyraString`, `LYRA_DEFAULT_STRINGS`, and the types
+`subscribeLyraLocale`, `bridgeLyraLocale`, `resolveLyraLocale`, `resolveLyraDirection`,
+`resolveLyraString`, `resolveLyraScopedString`, `LYRA_DEFAULT_STRINGS`, and the types
 `LyraLocaleStrings`, `LyraLocaleMeta`, `LyraLocaleDirection`, `LyraMessageKey`, `LyraMessage`,
-`LyraPluralMessage` and `LyraPluralCategory`. The package root continues to re-export the same
-surface for compatibility and remains registration-free; use the dedicated entry when the
-application only needs locale setup and the narrower import graph.
+`LyraPluralMessage`, `LyraPluralCategory`, `LyraLocaleBridgeOptions` and `LyraLocaleBridgeCleanup`.
+The package root continues to re-export the runtime for compatibility and remains registration-free;
+use the dedicated entry when the application only needs locale setup and the narrower import graph.
+The `@aceshooting/lyra-ui/utilities/localization.js` entry point is deprecated, with removal not
+before 23.0.0: every name it exports is exported here as the identical binding, so change the import
+specifier to `@aceshooting/lyra-ui/localization.js` and nothing else.
 **`LYRA_DEFAULT_STRINGS` is the authoritative key list** (matching the `LyraMessageKey` union) —
 read it to find the key to override rather than guessing one. Date, number, byte, relative-time and
 calendar output goes through `Intl`.
@@ -2186,14 +2217,20 @@ category selection walks the same chain, so the two can never disagree:
    ceiling retains its exact tag, base language and English fallback without constructing an
    unbounded prefix ladder; malformed over-complex inherited input goes directly to English.
 2. **Then any registered, well-formed BCP-47 catalog sharing the base language**, which is how a
-   _regional-only_ catalog is reached from a less specific tag: `lang="zh"` and `lang="zh-Hans"`
-   both find the shipped `zh-CN` catalog, while `lang="pt"` reaches `pt-BR` and an exact `lang="pt-PT"`
-   selects the European Portuguese catalog. Order within this
-   step is deterministic and independent of import order — most shared subtags first
-   (`zh-Hant-TW` prefers a registered `zh-TW` over `zh-CN`), then alphabetically as the tie-break
-   (bare `zh` with both registered picks `zh-CN`). Register the regional tag you actually mean if
-   the tie-break isn't the answer you want. Legacy/custom tags are exact/truncation-addressable
-   only and do not become regional siblings accidentally.
+   _regional-only_ catalog is reached from a less specific tag (`lang="zh"` finds `zh-CN`,
+   `lang="pt"` finds `pt-BR`). Order is deterministic and independent of import order:
+   1. **Same likely script** — the explicit script subtag, else CLDR likely subtags via
+      `Intl.Locale#maximize()`. `zh-Hant`, `zh-HK`, `zh-MO` and `zh-Hant-CN` reach Traditional
+      `zh-TW`; `zh`, `zh-Hans`, `zh-SG` and `zh-Hans-HK` reach Simplified `zh-CN`. An unknown
+      script (none, `Zzzz`, or no `Intl.Locale`) never matches.
+   2. **Same likely region** — a region-less tag reaches its CLDR default region: bare `pt` picks
+      `pt-BR` even with `pt-PT` imported.
+   3. **Most shared subtags**, counting each occurrence (`pt-AO` and `pt-MZ` pick `pt-PT`;
+      `qaa-Hant-TW` picks `qaa-TW` over `qaa-CN`).
+   4. **Alphabetical**, as a stable tie-break.
+
+   Register the regional tag you mean if the ordering isn't what you want. Legacy/custom tags are
+   exact/truncation-addressable only and never become regional siblings.
 3. **Then `en`**, always available through the built-in English defaults.
 
 Step 1 always beats step 2: with both `zh` and `zh-CN` registered, `zh-Hans-CN` resolves to `zh`.
@@ -2236,7 +2273,7 @@ through to the next valid tier.
 sorted, deduped and canonically spelled. `subscribeLyraLocaleRegistry(listener: () => void): () =>
 void` fires when registry membership grows, including for a newly registered locale that is not
 active; extending an existing catalog does not change membership and does not fire it.
-`subscribeLyraLocale()` (on `@aceshooting/lyra-ui/utilities/localization.js`) instead fires when the
+`subscribeLyraLocale()` (also on `@aceshooting/lyra-ui/localization.js`) instead fires when the
 active selection changes or a registration can alter the active locale's messages/direction, and
 filters unrelated registrations. Both return an idempotent unsubscribe. Delivery uses the eligible
 starting listener snapshots: one callback failure cannot prevent later active, component or
@@ -2279,11 +2316,11 @@ import "@aceshooting/lyra-ui/translations/ar.js"; // declares dir: 'rtl'; direct
 import "@aceshooting/lyra-ui/translations/fa.js"; // fa-IR falls back to this base catalog
 import "@aceshooting/lyra-ui/translations/he.js"; // he-IL falls back to this base catalog
 import "@aceshooting/lyra-ui/translations/it.js"; // Italian
-import "@aceshooting/lyra-ui/translations/pt-BR.js"; // serves generic pt and pt-BR
-import "@aceshooting/lyra-ui/translations/pt-PT.js"; // European Portuguese
+import "@aceshooting/lyra-ui/translations/pt-BR.js"; // Brazilian: serves pt and pt-BR
+import "@aceshooting/lyra-ui/translations/pt-PT.js"; // European: serves pt-PT, pt-AO, pt-MZ
 import "@aceshooting/lyra-ui/translations/ro.js"; // Romanian
-import "@aceshooting/lyra-ui/translations/zh-CN.js"; // serves zh, zh-Hans and zh-Hans-CN
-import "@aceshooting/lyra-ui/translations/zh-TW.js"; // Traditional Chinese
+import "@aceshooting/lyra-ui/translations/zh-CN.js"; // Simplified: serves zh, zh-Hans, zh-SG and zh-Hans-CN
+import "@aceshooting/lyra-ui/translations/zh-TW.js"; // Traditional: serves zh-Hant, zh-HK and zh-MO
 ```
 
 Persian and Hebrew use CLDR plural categories (`fa`: `one`/`other`; `he`:
@@ -2295,10 +2332,11 @@ and `he` declare `dir: 'rtl'`, so `getLyraLocaleDirection()`
 answers for them (and for `ar-EG`, `fa-IR`, `he-IL`) — but locale selection still does not _force_
 writing direction: set `dir="rtl"` on the page or an ancestor yourself.
 
-`de-CH`, `pt-BR`, `pt-PT`, `zh-CN`, and `zh-TW` are regional catalogs. Step 2 of the lookup order above
-still makes each reachable from a less-specific language tag, while an exact `lang="de-CH"`,
-`lang="pt-PT"` or `lang="zh-TW"` selects its dedicated regional catalog. They are listed under their real tags in
-`getRegisteredLyraLocales()`.
+`de-CH`, `pt-BR`, `pt-PT`, `zh-CN`, and `zh-TW` are regional catalogs: an exact tag always selects
+its own catalog, and a less specific tag reaches one through step 2 only when nothing on its
+truncation walk answers first (with `de` imported, `lang="de-AT"` resolves to `de`, never `de-CH`).
+The same routing drives plural selection and `getLyraLocaleDirection()`. They are listed under
+their real tags in `getRegisteredLyraLocales()`.
 
 Import only the locales the application can actually offer — each is a separate module, so unimported
 ones cost nothing. A catalog registered this way is merged like any other, so a later
@@ -2434,6 +2472,14 @@ import {
   validates them on `tool-upsert` events and `tool-call` parts: a non-finite or non-number time, or
   a `redactedFields` that is not an array of at most 100 strings of at most 4,096 characters, fails
   the event as `invalid_stream_event`.
+- **Tool display name and incomplete calls** (21.1.0) — `ToolInvocation.displayName` is the
+  application's own, already-translated tool label; `<lr-message-parts>` (both `tool-display`
+  modes) and `<lr-tool-timeline>` show it in place of `name`, which still selects the result
+  renderer. `status: 'incomplete'` marks a call that ended without a result (an interrupted stream,
+  a cancelled run); set it yourself on a `tool-upsert` or `tool-call` part, since the adapters never
+  infer it. The runtime accepts both on `tool-upsert` events, `tool-call` parts and message
+  snapshots; a `displayName` that is not a string of at most `maxIdentifierCharacters` fails the
+  event as `invalid_stream_event`, and a later upsert that omits it keeps the retained one.
 - **Resource limits** — pass a partial `AgentStreamLimits` to `createAgentStreamState()`, or adapter
   limit options to the relevant adapter. The exported `DEFAULT_AGENT_STREAM_LIMITS`,
   `DEFAULT_AI_SDK_ADAPTER_LIMITS`, `DEFAULT_AG_UI_ADAPTER_LIMITS`, and
@@ -3274,9 +3320,12 @@ readonly politeness: AnnouncementPoliteness; messageTtlMs: number; announce(text
 release(): void }`, and `AnnouncerTimerHost { setTimeout(handler: () => void, timeout: number):
 number; clearTimeout(handle: number): void }`.
 - **`localization` → `subscribeLyraLocale(listener): () => void` and
-  `bridgeLyraLocale(options?): () => void`** — the _active-locale_ half of the locale runtime,
-  which the side-effect-free `@aceshooting/lyra-ui/localization.js` entry does not carry (that one
-  has `subscribeLyraLocaleRegistry()`, which answers a different question — see "Localization").
+  `bridgeLyraLocale(options?): () => void`** — the _active-locale_ half of the locale runtime.
+  **This `utilities/localization.js` entry point is deprecated**, with removal not before 23.0.0:
+  import every name below from the side-effect-free `@aceshooting/lyra-ui/localization.js` entry,
+  which exports the identical bindings and types. The extensionless `@aceshooting/lyra-ui/utilities`
+  barrel keeps exporting them. `subscribeLyraLocale()` is distinct from
+  `subscribeLyraLocaleRegistry()`, which answers a different question — see "Localization".
   `subscribeLyraLocale()` fires whenever the active selection changes, and when a newly registered
   or extended catalog can alter that selection's messages or direction. Registrations unrelated to
   the active lookup chain are filtered. An application can therefore re-render its **own**
@@ -3299,8 +3348,7 @@ number; clearTimeout(handle: number): void }`.
   Its exact options record is `LyraLocaleBridgeOptions { target?: Element; direction?: boolean }`.
 
   ```ts
-  import { bridgeLyraLocale } from "@aceshooting/lyra-ui/utilities/localization.js";
-  import { setLyraLocale } from "@aceshooting/lyra-ui/localization.js";
+  import { bridgeLyraLocale, setLyraLocale } from "@aceshooting/lyra-ui/localization.js";
   import "@aceshooting/lyra-ui/translations/ar.js";
 
   const stop = bridgeLyraLocale(); // mirrors onto <html>
@@ -3311,13 +3359,13 @@ number; clearTimeout(handle: number): void }`.
   `resolveLyraScopedString(/* public names: host, key, defaults, overrides, fallback, values */):
 unknown` is a scoped variant of `resolveLyraString()` (see "Localization"): the same
 override → fallback → registered-locale-catalog resolution chain, but against a caller-supplied
-`defaults` record instead of the complete `LYRA_DEFAULT_STRINGS` catalog. It lives on this
-tree-shakable entry rather than the side-effect-free `@aceshooting/lyra-ui/localization.js` one so
-that resolving a handful of an application's own messages never pulls in the full compatibility
-catalog to do it — pass a small `defaults` object of just the keys used.
+`defaults` record instead of the complete `LYRA_DEFAULT_STRINGS` catalog, so resolving a handful
+of an application's own messages never needs the full compatibility catalog — pass a small
+`defaults` object of just the keys used. `@aceshooting/lyra-ui/localization.js` is side-effect-free,
+so a bundler drops the unused catalog; an unbundled graph that imports it still loads the catalog.
 
   ```ts
-  import { resolveLyraScopedString } from "@aceshooting/lyra-ui/utilities/localization.js";
+  import { resolveLyraScopedString } from "@aceshooting/lyra-ui/localization.js";
 
   const label = resolveLyraScopedString(host, "save", { save: "Save" });
   ```
@@ -3714,6 +3762,7 @@ These named interfaces and helper signatures are available to typed integrations
   `ToolInvocation {
   id: unknown;
   name: unknown;
+  displayName: unknown;
   args: unknown;
   status: unknown;
   result: unknown;
@@ -6757,8 +6806,12 @@ control, without making the control valid — see "The validity alias is cancela
 `label`, `next-icon`, `previous-icon`, and `start`. Lyra additionally retains `error`, which
 overrides `errorText`.
 
-The editable input shrinks first in a constrained row; `start` and `end` adornments are each
-capped at 40% and ellipsize unbroken content. Clear and calendar actions retain their fixed target.
+The editable input shrinks first in a constrained row. While a `start` or `end` adornment is shown
+it keeps a four-character floor, so a short adornment keeps its content width; without one it
+yields entirely to the clear and calendar actions. Adornments are sized to their content, each
+capped at 40%, and ellipsize unbroken content. Clear and calendar actions retain their fixed
+target, so a row with an adornment that is narrower than those actions plus the floor overflows
+rather than collapsing the field.
 
 **Custom states:** `blank`, `disabled`, `open`, and `range`; the shared form-associated mixin also
 exposes its validity states.
@@ -7358,6 +7411,13 @@ plus Shoelace aliases `prefix` → `start` and `suffix` → `end`.
 In a constrained button the default label ellipsizes and each adornment wrapper is capped at 40%
 of the control. Fixed icons remain visible while unbroken labels or metadata cannot widen the row.
 
+A detected icon-only label (the `icon-button` state) has no text to ellipsize, so it does not clip
+paint. A glow drawn around the glyph extends past the label box instead of being cut to a square,
+for example `gemstoneSelectedGlyphStyles`' drop-shadow halo on a `data-lr-gemstone-selected`
+wrapper. A text label keeps the truncation clip, even beside a glowing glyph. The `start`/`end`
+wrappers always clip, so put a glowing glyph in the default slot on its own. Hit area, focus ring,
+and label box are unchanged.
+
 **CSS parts:** `base` (compatibility name for the internal control; use `button`),
 `button` (the internal native `<button>`, or an `<a>` when `href` resolves to a safe link; it is
 the same node as `base`), `label`, `start`/`prefix` (the same wrapper), `end`/`suffix` (the same
@@ -7656,7 +7716,10 @@ sibling of it, not piped through `<lr-icon>`: the internal `<lr-icon>` mounts on
 set, so with `icon` left empty your content is the button's only child. That is what lets a
 complete element — an `<svg>`, an `<img>`, an `<lr-flag>` — render at its own natural aspect ratio
 instead of being forced into a 1:1 box. Setting both `icon` and slotted content renders both, side
-by side; that is a valid composition, not a fallback.
+by side; that is a valid composition, not a fallback. No wrapper sits between the slot and the
+native control, and that control declares no overflow clip. A glow painted around slotted content
+therefore keeps its full silhouette instead of being cut to the glyph's box. The
+`gemstoneAccentPicker` trigger's `gemstoneSelectedGlyphStyles` halo relies on this.
 
 **Bare SVG geometry fallback:** slotted bare SVG _geometry_ (`path`, `circle`, `rect`, `line`,
 `polygon`, `polyline`, `ellipse`, `g`, `use`) with no `icon` set and no enclosing `<svg>` of its
@@ -7948,8 +8011,15 @@ and cancellation rules. Never fires while `debounce` is unset, `0`, or non-finit
 `prefix` (alias of `start`), `suffix` (alias of `end`),
 `clear-button` (non-empty clearable `text`/`search` inputs only),
 `hint`/`form-control-help-text` (compatibility names on the same hint node), and `error`.
-Long `start`/`end` adornments shrink and ellipsize inside their flex allocation rather than
-widening a narrow field; label, hint, and error text wrap at unbroken boundaries. The
+In a constrained row the native field gives up its spare width first, so a short adornment such
+as a measurement unit (`kWh`) stays whole beside a narrow value. While a `start` or `end` adornment
+is shown the field keeps a four-character floor; only then do the adornments shrink: each is
+capped at half the row, and genuinely long adornments ellipsize inside that allocation rather than
+widening a narrow field. The floor holds against the fixed clear, password-toggle and stepper
+actions too, so a row with an adornment that is narrower than those actions plus the floor
+overflows rather than hiding the value. A row without adornments has no floor: its field still
+yields entirely to those actions. A shrink-to-fit container still sizes the field to its native
+intrinsic width. Label, hint, and error text wrap at unbroken boundaries. The
 `Narrow RTL (320px)` story exercises both adornments with a clear action and localized long copy.
 
 **The required marker.** `required` with a non-empty `label` paints the library's shared marker on
@@ -8229,6 +8299,10 @@ disabled state.
 
 The inherited `--lr-input-*` theme inputs keep `lr-input`'s ancestor-theme precedence; the number
 subclass does not redeclare them on its host.
+Beside the stepper pair it keeps `lr-input`'s constrained-row allocation: the number field gives up
+its spare width first, down to a four-character floor while a unit is shown, so a short `end` unit
+stays whole (the `Narrow Measurement Unit` story). A stepper row with a unit therefore needs room
+for the steppers plus that floor; without a unit the field still yields entirely to the steppers.
 It also installs the shared six-tier size sheet: stepper-bearing rows follow the same rendered
 action-height ladder as `lr-input` instead of remaining at the default tier for every `size`.
 
@@ -9305,6 +9379,136 @@ class AccentTrigger extends LitElement {
   tuning the gap and hit size small enough to avoid wrapping is a guess that breaks at the next
   swatch added.
 
+### gemstoneAccentPicker — the signature accent selector
+
+`gemstoneAccentPicker` names the canonical composition of `lr-icon-button`, `lr-popover`, and
+`lr-swatch-picker mode="gemstone"`. It is a **pattern name, not an exported component or tag**.
+Use it for application accent selection: a glowing current-gem trigger, one compact
+“Gemstone: selected name” caption, and all nine canonical gemstones, in `GEMSTONE_KEYS` order, in
+one row. Localize the caption, trigger, dialog, radiogroup, and item names. Omit introductory copy
+and a second selected-name paragraph.
+
+The consuming Lit component imports these granular entries and lists
+`gemstoneSelectedGlyphStyles` in its `static styles` ahead of the CSS that follows.
+`components/forms/icon-button/icon-button-register.js` can replace `icon-button.js` when no icon
+button in the application uses `icon` or `src`:
+
+```ts
+import '@aceshooting/lyra-ui/components/forms/icon-button/icon-button.js';
+import '@aceshooting/lyra-ui/components/overlays/overlay/popover.js';
+import '@aceshooting/lyra-ui/components/forms/swatch-picker/swatch-picker.js';
+import {
+  GEMSTONE_KEYS,
+  GEMSTONES,
+  gemstoneGlyph,
+  gemstoneSelectedGlyphStyles,
+  type GemstoneKey,
+} from '@aceshooting/lyra-ui/theme/gemstones.js';
+```
+
+`--accent-color`, `--caption-color`, and `--text-color` are application-owned theme tokens.
+`--lr-overlay-max-inline-size` lifts the popup's default 20rem cap so the 20rem palette plus the
+popover's own padding fits. Both `--lr-gemstone-selected-*` values reach the trigger glyph and the
+picker's checked glyph alike: a 0.42rem halo at 92% of the accent. Leave
+`--lr-gemstone-selected-shine-duration` unset to keep the default 1.8s shine. The
+`--lr-icon-button-*` values keep the trigger free of a rectangular fill at rest, on hover, and
+while pressed:
+
+```css
+.gemstone-accent-picker {
+  --lr-overlay-max-inline-size: 22rem;
+  --lr-gemstone-selected-color: color-mix(in srgb, var(--accent-color) 92%, transparent);
+  --lr-gemstone-selected-blur: .42rem;
+}
+.gemstone-accent-picker lr-icon-button {
+  --lr-icon-button-background: transparent;
+  --lr-icon-button-background-hover: transparent;
+  --lr-icon-button-background-active: transparent;
+  --lr-icon-button-border: none;
+}
+.gem { display: inline-flex; inline-size: 1.15rem; block-size: 1.15rem; }
+.gem svg { inline-size: 100%; block-size: 100%; }
+.palette {
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  gap: .15rem;
+  inline-size: 20rem;
+  padding: .3rem;
+}
+.heading {
+  margin: .2rem .3rem .5rem;
+  color: var(--caption-color);
+  font-size: .75rem;
+  font-weight: 600;
+}
+.name { color: var(--text-color); }
+.palette lr-swatch-picker {
+  padding: 0 .3rem .3rem;
+  --lr-swatch-picker-hit-size: 1.75rem;
+  --lr-swatch-picker-wrap: nowrap;
+  --lr-swatch-picker-gap: .25rem;
+}
+@media (max-width: 30rem) {
+  .palette { inline-size: auto; }
+  .palette lr-swatch-picker {
+    --lr-swatch-picker-hit-size: 1.5rem;
+    --lr-swatch-picker-gap: .125rem;
+  }
+}
+```
+
+At the default 16px root font size, `1.75rem`/`.25rem` give 28px targets with 4px gaps, and
+`1.5rem`/`.125rem` give 24px targets with 2px gaps. Below 30rem the palette shrinks to its row, so
+the popup fits a 320px viewport without scrolling. A `calc(100dvw - 2.5rem)` palette overflows the
+popup by 2px there. Apply `data-lr-gemstone-selected` to the transparent glyph wrapper, not the
+whole trigger, so the halo follows the gem's silhouette. The focus ring belongs to keyboard focus;
+do not add a permanent circular selection border. Leave the popover's default content padding and
+arrow intact.
+
+This Lit template assumes `selected` is a `GemstoneKey`. `accentLabel` names the dialog and the
+radiogroup. `triggerLabel(name)` (“Accent color: Ruby”), `captionLabel` (“Gemstone:”, with the
+locale's own separator), and `translateGemstone()` come from the application's catalog.
+`onAccentChange()` validates the string and updates application state:
+
+```ts
+// Build once per locale. A new array on every render re-creates every swatch and briefly blurs
+// the focused one.
+const items = GEMSTONE_KEYS.map((key) => ({
+  value: key,
+  color: GEMSTONES[key].fill,
+  label: translateGemstone(key),
+  gemstone: key,
+}));
+
+const name = translateGemstone(selected);
+html`
+  <lr-popover class="gemstone-accent-picker" placement="bottom-end"
+    popup-role="dialog" aria-label=${accentLabel}>
+    <lr-icon-button slot="trigger" label=${triggerLabel(name)}>
+      <span class="gem" data-lr-gemstone-selected aria-hidden="true">${gemstoneGlyph(GEMSTONES[selected].fill)}</span>
+    </lr-icon-button>
+    <div class="palette">
+      <p class="heading">${captionLabel} <span class="name">${name}</span></p>
+      <lr-swatch-picker mode="gemstone" aria-label=${accentLabel}
+        .items=${items} .value=${selected}
+        @lr-change=${(event: CustomEvent<{ value: string }>) => onAccentChange(event.detail.value)}>
+      </lr-swatch-picker>
+    </div>
+  </lr-popover>
+`;
+```
+
+The parts already supply the behavior, so do not re-implement it. The picker is a roving-tabindex
+`radiogroup` with `aria-checked` and a `:focus-visible` ring per swatch, and its Arrow keys swap
+under RTL. The popover keeps `bottom-end` on the logical end under RTL and returns focus to the
+trigger on Escape. `gemstoneSelectedGlyphStyles` stops the shine under
+`prefers-reduced-motion: reduce`. Verify 320px and desktop layouts, enlarged text, and both color
+modes. In a sidebar or settings panel, the caption and row may appear inline with the same glow
+and spacing; use the compact tier when the container is narrow and allow wrapping if even that
+tier cannot fit. Never shrink targets below 24px. Application theme application, default accent,
+validation, and persistence remain caller-owned.
+
 ---
 
 ## `lr-checkbox`
@@ -11487,8 +11691,9 @@ errors and own/fieldset validation barring), `lr-submit` (`detail: { value, item
 (`detail: { itemId }`, `skippable` only). `lr-invalid` (no detail) is the one bubbling/composed,
 cancelable alias emitted when the complete rubric fails a native validity check; preventing it also
 suppresses the native event's default validation UI.
-Native and prefixed input/change events from the composed child controls are contained; consumers
-above the rubric receive only the rubric-owned aggregate event shape.
+Native and prefixed input/change events from the composed child controls are contained, as is a
+multiple-category checkbox group's `lr-checkbox-group-toggle-request` proposal; consumers above the
+rubric receive only the rubric-owned aggregate event shape.
 
 **Methods:** `getForm()` returns the owning form. `setCustomValidity(message)` sets or clears a
 form-level error no per-key rule can
@@ -12319,14 +12524,17 @@ space-separated samples restores the attribute-driven path.
 **Slots:** none.
 
 **CSS parts:** `sparkline` and deprecated `base` are aliases on the same outer SVG, `fill` is the
-area path for solid/gradient appearance, `line` is the stroke path. Additive aliases are `area` on
-the same fill path and `bar` on each extension-mode rectangle.
+area path for solid/gradient appearance, `line` is the stroke path, and the additive `bar` is each
+extension-mode rectangle. `area` is a deprecated alias of `fill` on the same path (removal not
+before 23.0.0); use `::part(fill)`.
 
 **Themeable custom properties:** `--fill-color` (area/gradient stop color), `--line-color` (stroke
 color), and `--line-width` (stroke width). Each reads through the live CSS cascade; line/fill
 default to the selected `trend`'s semantic Lyra tokens and `--line-width` falls back through the
-compatibility `--lr-sparkline-stroke-width` to `--lr-border-width-medium`. No canvas bridge or
-manual refresh is needed.
+deprecated `--lr-sparkline-stroke-width` (removal not before 23.0.0) to `--lr-border-width-medium`.
+Replace that alias with `--line-width` scoped to the element (`lr-sparkline { --line-width: 2px; }`),
+since the unprefixed name also reaches any other element that reads it. No canvas bridge or manual
+refresh is needed. Styling hooks cannot be observed, so neither deprecated alias logs a warning.
 
 **Optional peer deps:** none.
 
@@ -12446,8 +12654,9 @@ value: string; readonly exactValue?: string }`; at most the first 10,000 rows ar
 
 **Events:** none.
 
-**Slots:** `start` (canonical leading icon), default (legacy leading-icon alias, retained as the
-fallback; `start` takes precedence when both are filled), `caption` (rich caption content —
+**Slots:** `start` (canonical leading icon), default (deprecated leading-icon alias, removal not
+before 23.0.0: it still renders while `start` is empty and `start` takes precedence when both are
+filled; move the icon to `slot="start"`), `caption` (rich caption content —
 overrides the `caption` attribute when slotted content is provided), `spark` (a sparkline, e.g. `<lr-sparkline
 slot="spark">`, or other compact trend visual — `lr-stat` only reserves the slot and doesn't
 render one itself), `sub` (rich sub-line content — overrides the `sub` attribute when slotted content
@@ -15623,7 +15832,10 @@ owns none of that.
 
 **Slots:** default (body content), `icon` (leading header glyph), `header` (replaces the built-in
 heading row entirely), `toolbar` (action row at the block-end edge; revealed by hover/focus on
-hover-capable devices and always visible with a coarse pointer or no hover).
+hover-capable devices and always visible with a coarse pointer or no hover; it also stays revealed
+while an `lr-dropdown`, `lr-popover` or `lr-context-menu` opened from it is open, because that menu
+sits in the browser top layer, where Chromium and WebKit stop matching `:hover`/`:focus-within` on
+the node).
 
 **CSS parts:** `base` (the row wrapping the input handles, the card and the output handles — it
 carries no card chrome of its own), `card` (the bordered, filled node card), `header`, `icon`,
@@ -16398,9 +16610,9 @@ button, while `error` is set.
 selection stays silent; every post-mount `selectedDocumentIds` change appends the localized selected count
 to the document's shared light-DOM polite sink, including zero and repeated equal counts.
 Internal search, tag-filter, and checkbox native `input`/`change` plus prefixed `lr-input`/
-`lr-change` aliases, the tag combobox's lifecycle/filter/clear/invalid events, table pagination and
-priority-column visibility events, and the table's click-anywhere selection event stop at the
-component's translation boundary. The table is still in multiple-selection semantics so
+`lr-change` aliases, the checkboxes' `lr-checkbox-toggle-request` proposals, the tag combobox's
+lifecycle/filter/clear/invalid events, table pagination and priority-column visibility events, and
+the table's click-anywhere selection event stop at the component's translation boundary. The table is still in multiple-selection semantics so
 `selectedDocumentIds` reaches row `aria-selected`; document selection itself remains checkbox-owned, while
 row activation opens the document. Listen for the document-library events above; one interaction
 emits one documented host contract without also leaking a composed child event.
@@ -17725,9 +17937,11 @@ custom-handle content inside the separator; its assigned subtree is inert, so th
 the sole pointer/keyboard resize control). Under RTL, logical start/end and horizontal pointer/arrow
 behavior mirror together; vertical behavior does not invert.
 
-**CSS parts:** `base split-panel` (both tokens are on the same outer wrapper), `start panel` and
+**CSS parts:** `base split-panel` (both tokens are on the same outer wrapper; `split-panel` is a
+deprecated alias of `base`, removal not before 23.0.0, so style `::part(base)`), `start panel` and
 `end panel` (each pane exposes its individual token plus the shared `panel` token), `divider`
-(focusable `role="separator"`, with value/min/max and disabled ARIA state).
+(focusable `role="separator"`, with value/min/max and disabled ARIA state). The deprecated part
+still matches until its removal; being a stylesheet selector, it logs no runtime warning.
 
 **Themeable custom properties:** `--divider-width` (default `4px`), `--divider-hit-area` (requested
 default `12px`, with Lyra's `--lr-icon-button-size` minimum target remaining the floor), `--min`
@@ -19683,9 +19897,10 @@ letting a consumer that syncs app chrome to the rail's mode pick up the restored
   the host's re-render has applied. That second pass only acts while focus is still inside the rail
   or has fallen to `<body>` — focus moved elsewhere in the meantime is never taken back — and
   focuses the first candidate that can actually hold focus: the trigger, then the element that held
-  focus when the overlay opened, then the built-in `[part='toggle']` (unavailable under
-  `hideToggle`), and finally the rail host; when even the host cannot take focus (hidden, or inert —
-  under an inert ancestor or behind a stacked modal), focus is left where it is. The host
+  focus when the overlay opened (none when focus was on `<body>`), then the built-in
+  `[part='toggle']` (unavailable under `hideToggle`), then the rail host, and finally
+  `focusFallback` when set; when none of them can take focus (the host hidden, or inert — under an
+  inert ancestor or behind a stacked modal), focus is left where it is. The host
   temporarily receives `tabindex="-1"` only when it has no authored tabindex; the temporary
   attribute is removed once focus moves off the host or the rail disconnects, while a blur caused
   only by the window or tab losing system focus (the host stays the focused element) leaves it in
@@ -19698,7 +19913,8 @@ letting a consumer that syncs app chrome to the rail's mode pick up the restored
   `null`), no external element is a return candidate: a close still returns focus to the built-in
   toggle when its own click opened the overlay, otherwise to the element that held focus at open,
   and the deferred pass still runs over its remaining candidates (that element, the built-in toggle,
-  then the rail host) — only the trigger candidate depends on the association. The resolved trigger
+  the rail host, then `focusFallback`) — only the trigger candidate depends on the association. The
+  resolved trigger
   also receives `aria-expanded` (rendered in both states) and `aria-controls` pointing at the rail's
   own panel, so an external control announces the overlay's state across the shadow boundary.
   Because a light-DOM element cannot hold a raw reference into another element's shadow tree,
@@ -19710,6 +19926,29 @@ letting a consumer that syncs app chrome to the rail's mode pick up the restored
   label/`htmlFor`-style alternative to assigning `trigger` directly (mirrors `<lr-page-rail>`'s
   `for`). Resolved against this element's own root (shadow root or document) when the overlay opens
   and again when it closes. Ignored once `trigger` is itself set.
+- `focusFallback: HTMLElement | string | null = null` (attribute `focus-fallback`) — opt-in
+  last-resort target for the mobile overlay's deferred focus return, tried only after every built-in
+  target (the `trigger`/`for` association, the element that held focus at open, `[part='toggle']`,
+  the rail host) is unavailable — typically the application's main region, for a host that takes the
+  navigation, or the region around it, out of the layout as the overlay closes. Accepts an element or
+  an id, the same element-or-id shape as `<lr-intersection-observer>`'s `root`; an id (the attribute
+  always holds one — an id, not a selector) is resolved like `for`, against the rail's own root
+  (shadow root or document), and `''` means unset. Resolved when the deferred pass runs, so
+  reassigning it after opening, or re-creating the element under the same id before the pass runs,
+  is honored; property and attribute writes set the same value and the last write wins. It never
+  outranks a target that can take focus, so it changes no close that already lands, and it is not
+  used by the synchronous attempt, by a close caused by leaving `'mobile'` (a breakpoint or
+  `forceMode` change), or in the full/icon-only presentations. A target that is missing,
+  disconnected, in another document, hidden, inert or under an inert ancestor, `aria-hidden`,
+  disabled, or not focusable leaves focus where it is, and so does anything inside this rail
+  (unavailable whenever the rail host is). The target needs `tabindex="-1"` (or another way to take
+  focus): unlike the host, the rail never adds a tabindex to it. Unset (`null`) reproduces the
+  existing behavior exactly.
+
+  ```html
+  <main id="content" tabindex="-1">…</main>
+  <lr-app-rail hide-toggle for="menu-button" focus-fallback="content">…</lr-app-rail>
+  ```
 - `resizable: boolean = false` (reflected) — opts a continuously draggable width in for the `'full'`
   state, exposing a `[part='resizer']` handle clamped to `[minRailWidthPx, maxRailWidthPx]`. `false`
   (the default) renders no resizer and leaves the fixed-width `--lr-app-rail-width` CSS token
@@ -20516,11 +20755,14 @@ is neutral. This is also the composition used for direct `<lr-dropdown-item>` ch
   Preventing it anywhere keeps the current menu/submenu chain open. There are no
   `lr-menu-select`, `lr-menu-item-select`, or nested-selection aliases.
 
-**Slots:** default (`<lr-menu-item>`/`<lr-dropdown-item>` plus semantic separators), `header`, and
-`footer`. Header and footer are composed controls or explanatory regions outside the
-`role="menu"` list, so filters, counts, or footer actions do not violate the menu required-child
-contract. Arbitrary non-item content in the default slot still renders, but is not enrolled as a
-menu item.
+**Slots:** default (`<lr-menu-item>`/`<lr-dropdown-item>` rows, `<lr-menu-label>` captions, and
+`<hr>`/`<lr-divider>` separators), `header`, and `footer`. Header and footer are composed controls
+or explanatory regions outside the `role="menu"` list, so filters, counts, or footer actions do not
+violate the menu required-child contract. Any other default-slot content is deprecated (removal not
+before 23.0.0): it still renders, but inside `role="menu"` without a menu-item role and skipped by
+keyboard navigation, so move it to `slot="header"` or `slot="footer"`. Content that `lr-dropdown`
+forwards into its own menu is not covered: its default slot mirrors `sl-dropdown`'s free-form
+content.
 
 **CSS parts:** `header`, `list`, and `footer`. Root `trigger` and `popup` parts do not exist;
 style those on `<lr-dropdown>` when using the overlay composition.
@@ -23521,8 +23763,8 @@ that override no longer decides anything for their modal instances and can be dr
 still resolves the `z-index` in their stylesheet, but only as the fallback for a user agent without
 popover support. A `contained` drawer is deliberately nonmodal and is not promoted. The token keeps
 doing real work everywhere else it is used: `lr-popover`, `lr-dropdown` and `lr-tooltip` are not
-promoted unless trapped (below), and otherwise go on stacking at `--lr-overlay-stack-index`,
-falling back to `--lr-layer-popover`.
+promoted unless trapped (below) or, for `lr-popover` and `lr-dropdown`, opted in with `top-layer`,
+and otherwise go on stacking at `--lr-overlay-stack-index`, falling back to `--lr-layer-popover`.
 
 **Anchored overlays and the top layer.** An anchored overlay that resolves the `fixed` strategy
 (dropdowns, popovers, tooltips, selects, comboboxes, date/time inputs, colour pickers, submenus,
@@ -23546,6 +23788,29 @@ at UI scale with either strategy. The full-viewport modal surfaces that are not
 `lr-widget`, the `lr-responsive-panel` overlay and `lr-tour`'s spotlight) still stack with
 `z-index`: do not place them under a transformed, filtered or contained ancestor.
 
+An ancestor that is only a **stacking context** does not trap an overlay, so it is not promoted: a
+popover inside a `position: fixed` (or `sticky`) header with `z-index: 1000` still paints beneath a
+sibling surface at `z-index: 1100`, and no `z-index` on the popup can lift it out of the header's
+context. For that case `lr-popover` and `lr-dropdown` take an explicit opt-in, `top-layer`: the open
+popup is always shown in the browser top layer, placed `fixed`, with anchoring, the arrow, RTL
+placement, focus, Escape, light dismiss and the transitions unchanged, and no DOM node moved.
+Stacking contexts are deliberately not detected automatically: every `fixed` or `sticky` ancestor
+creates one, and so does almost every `z-index`ed, translucent (`opacity`) or `isolation: isolate`d
+one; most of them never cover the overlay, and promoting through each would lift overlays above
+layers that pages order on purpose (including their own toasts and sticky chrome). Whether a
+stacking context actually hides an overlay depends on sibling layering elsewhere on the page, which
+only the page knows, so the page opts in per instance.
+
+```html
+<header style="position: fixed; inset-block-start: 0; inset-inline: 0; z-index: 1000">
+  <lr-popover top-layer placement="bottom-start">
+    <button slot="trigger">Account</button>
+    <nav aria-label="Account"><a href="/profile">Profile</a></nav>
+  </lr-popover>
+</header>
+<div class="search-panel" style="position: fixed; z-index: 1100">…</div>
+```
+
 **Initial focus.** An `[autofocus]` element anywhere in the slotted content takes focus when the
 overlay opens — including one inside a slotted custom element's own open shadow root, so
 `<lr-input autofocus>` behaves like `<input autofocus>`. With nothing marked, a modal (`lr-dialog`,
@@ -25012,6 +25277,16 @@ If the import fails, leave the native disclosure visible and usable.
   escapes transformed, filtered or contained ancestors by promoting the popup into the browser top
   layer where the native Popover API exists; otherwise, as before, such an ancestor contains and
   clips it (see **Anchored overlays and the top layer**).
+- `topLayer: boolean = false` (attribute `top-layer`, reflected) — always shows the open popup in
+  the browser top layer where the native Popover API exists, so it paints above every page layer
+  whatever the stacking contexts around it: the fix for a popover in a `z-index`ed fixed or sticky
+  header, toolbar or rail that a sibling surface stacked higher would otherwise cover. While set the
+  popup is placed with the `fixed` strategy whatever `positioning-strategy` resolves to (the
+  property still reads back its own value). Anchoring, the arrow, RTL placement, focus, Escape,
+  light dismiss, the hover bridge and the show/hide transition are unchanged, because no DOM node
+  moves; the popup stays promoted through its hide transition and leaves the top layer once it
+  settles closed. Changes apply live while open. Without native Popover API support the popup keeps
+  its ordinary `z-index` stacking. Unset, nothing changes: only a trapping ancestor promotes it.
 - `trigger: string = 'click'` — a _space-separated_ list of `click` (the shipped behaviour),
   `hover`, `focus` and `manual`, spelled exactly the way `<lr-tooltip>`'s `trigger` is, so
   `trigger="hover focus"` means the same thing on both. `LyraPopoverTrigger` is the type of one
@@ -25541,6 +25816,12 @@ its surface.
   inherits `<lr-popover>`'s `trigger`/`showDelay`/`hideDelay`/`hoverBridge`, and honors the
   cascading `--lr-positioning-strategy` custom property ahead of this mirrored `absolute` default
   when neither spelling is authored on the instance.
+- `topLayer: boolean = false` (attribute `top-layer`, reflected) — inherited from `<lr-popover>`:
+  always shows the open menu in the browser top layer, placed `fixed` whatever
+  `positioning-strategy`/`hoist` say, so a dropdown in a `z-index`ed fixed header opens above a
+  sibling surface stacked higher. Submenus of a promoted menu stay above the sibling surface too.
+  Unset, a dropdown is promoted only when a trapping ancestor forces it (see **Anchored overlays
+  and the top layer**).
 - `containingElement?: HTMLElement` (property only) — an external element that counts as inside for
   light-dismiss handling.
 - `arrow`, `withoutArrow` (`without-arrow`), `arrowPlacement`, `arrowPadding`, and `accessibleLabel`
@@ -27229,11 +27510,16 @@ adds no layout.
 needed; reflected), `attr: string | null = null` (reflected; `*` observes every attribute; otherwise a
 space-separated filter), `attrOldValue: boolean = false` (`attr-old-value`), `charData: boolean =
 false` (`char-data`), and `charDataOldValue: boolean = false` (`char-data-old-value`); all four
-mapped attributes reflect. Lyra's
-existing aliases remain and also reflect: `observeAttributes` (`attributes`; unfiltered boolean
-form of `attr`, equivalent to `attr: '*'`) and `characterData` (`character-data`, equivalent to
-`charData`). Plus `subtree: boolean = true`, and programmatic `attributeFilter: string[] = []`
-(neither reflects).
+mapped attributes reflect. Plus `subtree: boolean = true`, and programmatic
+`attributeFilter: string[] = []` (neither reflects).
+
+**Deprecated aliases** (still functional and still reflecting until their removal, no earlier than
+23.0.0; setting either logs a one-time development warning): `observeAttributes` (`attributes`)
+turns on attribute observation, and `characterData` (`character-data`) is identical to `charData`.
+Replace `character-data` with `char-data`. Replace `attributes` with `attr="*"` only when `attr`,
+`attr-old-value` and `attributeFilter` are all unset; otherwise just remove it. Those already turn
+attribute observation on, and a non-null `attr` ignores `attributeFilter`, so adding `attr="*"` next
+to a filter would widen the observer to every attribute.
 
 The browser capability is optional. A missing or throwing owner-window lookup, or an unavailable or
 throwing constructor, leaves that rebuild inert rather than leaking an exception. Individual
@@ -28091,9 +28377,14 @@ Pairs with `lr-icon-button` (see `llms/components/lr-icon-button.md`).
   `flip`, `flip-360`, `shake`, `spin`, `spin-pulse`, `spin-reverse`, `spin-snap`, `spin-snap-4`,
   `spin-snap-8`, `buzz`, `wag`, `float`, `swing`, or `jello`. Every treatment stops under
   `prefers-reduced-motion: reduce`.
-- `fixedWidth: boolean = false` (attribute `fixed-width`, reflected) — widens the icon _box_ to
-  `--lr-icon-fixed-width` while the glyph keeps `--lr-icon-size` and centres inside it, so a column
-  of differently-shaped icons lines its labels up.
+- `fixedWidth: boolean = false` (attribute `fixed-width`, reflected, deprecated; removal not before
+  23.0.0) — widens the icon _box_ to `--lr-icon-fixed-width` while the glyph's svg is pinned to
+  `--lr-icon-size` (1em by default) and centres inside it, so a column of differently-shaped icons
+  lines its labels up. It keeps working unchanged, and setting it logs a one-time development
+  warning. Omit it: the default canvas already gives every icon the same 1.25em box. For the wider
+  1.5em box set `lr-icon { inline-size: var(--lr-size-1-5em); }` on the host instead. One geometry
+  difference: a glyph wider than 1em keeps its intrinsic width (up to the box) instead of being
+  squeezed to 1em.
 
 **Events:**
 
@@ -28128,8 +28419,9 @@ source tree.
 - `--lr-icon-size` (unset by default) — when supplied, overrides both canvas dimensions. Without
   it, the selected `canvas` uses the font-relative sizes above. Stroke color is `currentColor` and
   the host is `color: inherit`, so color comes from surrounding text with no configuration.
-- `--lr-icon-fixed-width` (default `--lr-size-1-5em`) — inline size of the box while `fixed-width`
-  is set.
+- `--lr-icon-fixed-width` (default `--lr-size-1-5em`; deprecated together with `fixed-width`,
+  removal not before 23.0.0) — inline size of the box while `fixed-width` is set. Set `inline-size`
+  on the host instead.
 - `--lr-icon-rotate` (default `0deg`), `--lr-icon-flip-x` and `--lr-icon-flip-y` (default `1` each) —
   the transform inputs. `--lr-icon-rotate` is written inline from the `rotate` property and the flip
   factors are set to `-1` by `flip`, so set those properties rather than these tokens.
@@ -28197,7 +28489,7 @@ unregisterIconLibrary("material"); // icons using it revert to the built-in glyp
   name="star"
   label="Favourite"
 ></lr-icon>
-<lr-icon library="material" name="delete" fixed-width></lr-icon>
+<lr-icon library="material" name="delete"></lr-icon>
 <lr-icon name="search" canvas="square" animation="beat"></lr-icon>
 ```
 
@@ -29071,7 +29363,15 @@ Also exported from the package root:
 `languageToCountry(language: string): string | undefined` and the `LANGUAGE_TO_COUNTRY` lookup
 table (region subtag wins, e.g. `en-US` → `us`; plain `en` → `gb`; override the table per-app if you
 need different defaults). Only the table's own entries are eligible for base-language fallback;
-inherited object members such as `constructor` resolve to `undefined`. Also exported:
+inherited object members such as `constructor` resolve to `undefined`. A region-less tag whose
+script subtag implies a different likely region than its bare language takes that region instead of
+the table default, so Traditional and Simplified Chinese never share a flag: `zh-Hant` → `tw` while
+`zh` and `zh-Hans` → `cn`. The rule is not specific to Chinese: `zh-Hanb` and `zh-Bopo` → `tw`, and
+`kk-Arab` (Kazakh in Arabic script, as written in China) → `cn` rather than the `kk` default of `kz`;
+pass `country` when a different flag is wanted. A script that implies the language's own likely
+region keeps the table's convention (`en-Latn` → `gb`), a language with no table entry stays
+unresolved, and an engine without `Intl.Locale` likely-subtags data uses the table default. Also
+exported:
 `localeNativeName(tag: string): string`.
 
 `localeNativeName()` returns a BCP-47 tag's **endonym** — the locale's name written in that locale
@@ -29345,7 +29645,16 @@ modes use the same expression semantics at initial render and after a theme chan
 **Properties:**
 
 - `center: [number, number] = [0, 0]`
-- `zoom: number = 2`
+- `zoom: number = 2` — `center` and `zoom` are the declarative camera. Assigning either moves the
+  map without emitting anything. When the camera settles after a user gesture or `fitBounds()`, the
+  element writes that camera into both and reports it through `lr-map-view-change`, so its next
+  update never resets it, and a later, different assignment still moves the map. Assigning a value
+  the map already shows moves nothing, so echoing a reported camera back, however late, never stops
+  an animation or gesture. An assignment that does interrupt one (a fit still animating, a
+  gesture's inertia) applies the whole declared camera, `center` and `zoom` alike, so the axis you
+  did not assign is not left wherever the interrupted movement stopped; with nothing in flight,
+  only the assigned axis moves. Because both track the settled camera, a map rebuilt after a
+  disconnect/reconnect opens at the last settled camera rather than the originally declared one.
 - `renderWorldCopies?: boolean` (attribute: false) — forwarded to MapLibre when its map is
   constructed. Leave it unset to preserve MapLibre's own current default; set `false` before
   construction to stop repeating the world horizontally. This is a construction-time option, so a
@@ -29760,6 +30069,73 @@ shared `maplibre-gl` import without constructing a map or allocating a WebGL con
 `false` when the peer is unavailable, allowing an application to choose a fallback before connecting
 an element.
 
+`fitBounds(bounds: LyraMapBounds, options?: LyraMapFitBoundsOptions): boolean` frames a box
+`[[west, south], [east, north]]` in the viewport: the way to show every current marker, or a
+selected region, whenever the data set changes. Use it instead of calling the peer's own
+`fitBounds()` through `map`, which the element neither knows about nor reports. Once the camera
+settles, the element writes it into `center`/`zoom` and emits `lr-map-view-change` with
+`source: 'fit'`, so declarative state stays in sync and the element never resets the fitted camera.
+
+- `options.padding` — screen pixels kept clear around the box: one number for every side, or a
+  `LyraMapPadding { top?, right?, bottom?, left? }`. The sides are the viewport's physical sides in
+  both text directions, because the map's projected space is physical. A negative or non-finite
+  side counts as `0`. Defaults to `0`.
+- `options.maxZoom` — the highest zoom the fit may reach, so one marker or a tight cluster does not
+  zoom to the street. Clamped into `[0, 22]`; a non-finite value sets no ceiling.
+- `options.animate` — defaults to `true`. The camera never animates under
+  `prefers-reduced-motion: reduce`.
+- Latitudes lie in `[-90, 90]`, with `south <= north`, and longitudes in `[-180, 180]`. A box
+  crossing the antimeridian takes either of MapLibre's forms: `west > east`, or `east` unwrapped
+  past 180, up to one full turn east of `west` (`[[170, -10], [190, 10]]`, the form MapLibre's
+  `LngLatBounds` produces). A single point is a valid zero-size box; pair it with `maxZoom`.
+  Anything else (non-finite or non-number values, out-of-range coordinates, an inverted latitude
+  span, the wrong shape) returns `false` without moving or queueing anything, with a
+  development-mode warning.
+- Callable before the map exists, whether the peer is still loading or an off-screen map has not
+  been constructed yet. The most recent request is queued and applied without animation right
+  after construction, unless `center` or `zoom` has been given a different value since the call.
+  Re-assigning the value already held (a framework re-render building an equal array, say) keeps
+  the queued fit.
+- A `center`/`zoom` assignment made while a fit is still animating wins: the interrupted fit is
+  neither written back nor reported, and the camera lands on the whole declared `center`/`zoom`.
+- Returns `true` once the fit is running or queued, and `false` when the loaded peer cannot fit a
+  box. When the padded box cannot fit the map's current size (padding wider or taller than the
+  map), MapLibre leaves the camera where it is and logs its own warning: the call still returns
+  `true`, and no `lr-map-view-change` fires.
+
+There is deliberately no declarative `bounds` property. `center` and `zoom` already describe the
+camera; a third camera input would need a precedence rule against them, and a framework that
+rebuilds its arrays on every render would refit on every render, pulling the camera away from a user
+who has just panned. A one-shot command whose result lands in `center`/`zoom` keeps one camera input.
+
+```ts
+import type {
+  LyraMap,
+  LyraMapBounds,
+  LyraMapMarker,
+  LyraMapViewChangeDetail,
+} from '@aceshooting/lyra-ui/components/media/map/map.class.js';
+
+let camera: LyraMapViewChangeDetail | undefined;
+const mapEl = document.querySelector('lr-map') as LyraMap;
+mapEl.addEventListener('lr-map-view-change', (event) => {
+  // Keep the host's own camera state in step: { center, zoom, source }.
+  camera = event.detail;
+});
+
+function showMarkers(markers: LyraMapMarker[]): void {
+  mapEl.markers = markers;
+  if (markers.length === 0) return;
+  const lngs = markers.map((marker) => marker.lngLat[0]);
+  const lats = markers.map((marker) => marker.lngLat[1]);
+  const box: LyraMapBounds = [
+    [Math.min(...lngs), Math.min(...lats)],
+    [Math.max(...lngs), Math.max(...lats)],
+  ];
+  mapEl.fitBounds(box, { padding: 48, maxZoom: 14 });
+}
+```
+
 **Events:** `lr-map-load` (fired once, after the underlying map's own `'load'`),
 `lr-map-legend-toggle` (**cancelable**; frozen `LyraMapLegendToggleDetail { value, visible,
 hiddenCategories }` — the activated row's category key, its proposed visibility, and the complete
@@ -29792,7 +30168,16 @@ separately because it is a synthetic aggregate rather than one of your features:
 is MapLibre's `point_count`/`point_count_abbreviated`/`cluster_id` properties, which is what a
 zoom-to-cluster handler reads. The count label is deliberately not hit-tested (it sits exactly on
 the circle already queried and would only make the label the topmost hit), and a `kind: 'heatmap'`
-layer is never queried at all — MapLibre returns no features for a rendered density surface
+layer is never queried at all — MapLibre returns no features for a rendered density surface.
+Also `lr-map-view-change` (non-cancelable; frozen `LyraMapViewChangeDetail { center, zoom, source }`,
+`source` being `LyraMapViewChangeSource = 'user' | 'fit'`), fired once each time the camera settles
+after a user gesture (drag, wheel, touch, keyboard, Shift+drag box zoom, or a standard peer
+navigation button) or a `fitBounds()` call. `center` is `[longitude, latitude]` with the longitude
+wrapped into `[-180, 180]`. The element has already written the camera into `center` and `zoom`
+when it fires, so a host that mirrors camera state assigns the detail back, at any later time,
+without moving the map. Assigning `center`/`zoom` reconciles without emitting it, so a controlled
+host cannot loop, and camera moves made directly through `map` are not reported — which is why
+`'user'` and `'fit'` are the only sources.
 
 The outer marker-activation detail is frozen, while an opaque marker `unsafeHtml` value remains the
 original supplied value at the MapLibre popup and marker-activation boundary. Treat it as trusted
@@ -30999,7 +31384,8 @@ and later MIME values restore detection.
   button and the `kind="video"` `open-button` render `disabled`; a safe file chip's anchor loses
   its `href` and `download`, so it genuinely cannot fetch, and gains an explicit `role="link"` so
   its accessible name and `aria-current` stay valid on an element that no longer has an implicit
-  role. `lr-media-open` and `lr-before-media-download` stop firing from every path, `click()`
+  role. `lr-media-open`, `lr-media-download-request` and its deprecated `lr-before-media-download`
+  alias stop firing from every path, `click()`
   included, the action leaves the tab order, and it paints at `--lr-opacity-disabled` with a
   `not-allowed` cursor. Deliberately does NOT reach into the `kind="video"` player: `<video
   controls>` is media content with its own native transport, not this card's action. An
@@ -31031,9 +31417,13 @@ not exports from the component entry.
 **Events:** `lr-media-open` (`detail: LyraMediaCardOpenDetail { src: string; filename: string }`,
 noncancelable) notifies
 after image-card or video open-button activation; those kinds have no component-owned navigation,
-so a host decides what "open" means. `lr-before-media-download` carries the same detail and is
+so a host decides what "open" means. `lr-media-download-request` carries the same detail and is
 cancelable only for a safe file anchor immediately before its native download/open default; calling
-`preventDefault()` there suppresses that exact default. `detail.src` is whichever internally
+`preventDefault()` there suppresses that exact default. `lr-before-media-download` is its deprecated
+alias (removal not before 23.0.0): it still fires right after the canonical event from the same
+activation, with an equal but separate `detail`, and either event's `preventDefault()` vetoes the
+download/open. A veto through the alias logs a one-time development warning, so move listeners to
+`lr-media-download-request`. `detail.src` is whichever internally
 validated safe-URL sink actually rendered, not necessarily the raw `src` property verbatim — a
 whitespace-padded value is trimmed, so it matches the rendered sink.
 The former generic `lr-open` event is removed in v9: notification and veto phases now have distinct,
@@ -31089,7 +31479,7 @@ sizing), `--lr-focus-ring-*`, `--lr-transition-fast`.
     .addEventListener("lr-media-open", (e) => openLightbox(e.detail.src));
   document
     .getElementById("file-card")
-    .addEventListener("lr-before-media-download", (e) => shouldUseNativeDownload || e.preventDefault());
+    .addEventListener("lr-media-download-request", (e) => shouldUseNativeDownload || e.preventDefault());
 </script>
 ```
 
@@ -32527,11 +32917,15 @@ These named interfaces and helper signatures are available to typed integrations
     setZoom(zoom: number): unknown;
     resize(): unknown;
     setMaxBounds?(bounds: readonly [readonly [number, number], readonly [number, number]] | null): unknown;
+    fitBounds?(bounds: [[number, number], [number, number]], options: Record<string, unknown>, eventData: Record<string, unknown>): unknown;
+    isMoving?(): boolean;
     remove(): void;
     on(type: 'error', listener: (event: {
       error?: unknown;
     }) => void): this;
     on(type: 'load', listener: () => void): this;
+    on(type: 'moveend', listener: (event: Readonly<Record<string, unknown>> | undefined) => void): this;
+    on(type: 'boxzoomend', listener: () => void): this;
     on(type: 'click', listener: (event: {
       point: unknown;
       lngLat: {
@@ -32721,6 +33115,26 @@ These named interfaces and helper signatures are available to typed integrations
     readonly open: boolean;
   }`
   Import: `@aceshooting/lyra-ui/components/media/map/map.class.js`.
+  `LyraMapPadding {
+    readonly top?: number;
+    readonly right?: number;
+    readonly bottom?: number;
+    readonly left?: number;
+  }`
+  Import: `@aceshooting/lyra-ui/components/media/map/map.class.js`.
+  `LyraMapFitBoundsOptions {
+    readonly padding?: number | LyraMapPadding;
+    readonly maxZoom?: number;
+    readonly animate?: boolean;
+  }`
+  Import: `@aceshooting/lyra-ui/components/media/map/map.class.js`.
+  `LyraMapViewChangeDetail {
+    readonly center: readonly [number, number];
+    readonly zoom: number;
+    readonly source: LyraMapViewChangeSource;
+  }`
+  `LyraMapViewChangeSource = 'user' | 'fit'`.
+  Import: `@aceshooting/lyra-ui/components/media/map/map.class.js`.
   `LyraMapStyleSpecification {
     readonly version: 8;
     readonly sources: Readonly<Record<string, unknown>>;
@@ -32996,11 +33410,10 @@ structured points retain their y-value formatting.
   axes, `'r'` for a radar/polar-area ring, and `undefined` where there is no axis at all (a
   pie/doughnut slice). Two value axes usually exist precisely because they carry different units,
   so without it one formatter cannot render a secondary axis correctly. `datasetIndex`, `index`,
-  `label` and `seriesLabel` now reach the `tick`, `tooltip`, `legend` and `visual` surfaces as well
-  as the `table`, `export` and `spoken` ones they always reached, and indexes are reported in
-  source space — the same space the data table, the CSV export and `lr-point-click` use. Every one
-  of these fields was `undefined` before, so no existing formatter changes behaviour. A
-  `stackTotals`/`tableTotals` stack total is the exception in the other direction: it is a sum
+  `label` and `seriesLabel` reach the `tooltip`, `legend`, `visual`, `table`, `export` and `spoken`
+  surfaces, with indexes in source space — the same space the data table, the CSV export and
+  `lr-point-click` use. A `tick` call carries `axis` but none of those four. A
+  `stackTotals`/`tableTotals` stack total is also an exception: it is a sum
   *across* the stack's datasets, so it carries `statistic: 'total'`, the category `index`/`label`
   and the stack's own `axis`, but no `datasetIndex` and no `seriesLabel` — naming the topmost
   series would make a unit-switching formatter render that one series' unit for a cross-series
@@ -33468,7 +33881,9 @@ is no "every item in the tooltip" surface to hook a title or footer formatter on
   them side by side; ignored for `type="line"`
 - `tickFormat?: (value: number) => string` (attribute: false) — formats a y-axis tick value for
   display (e.g. `(v) => \`$${v.toFixed(2)}\`` for currency, or a duration formatter for `"42s"`).
-  Falls back to the built-in "nice numbers" formatter when unset.
+  Falls back to the built-in "nice numbers" formatter when unset. The returned string is painted
+  bidi-isolated, so `2.4 MiB/s` keeps its number-unit order under `dir="rtl"` (see
+  [Formatted labels in right-to-left layouts](#formatted-labels-in-right-to-left-layouts)).
 - `formatter?: LyraChartFormatter` (attribute: false) — family-wide context-object formatter used
   by visual/tooltips, spoken text, legends, tables, and CSV export. It takes precedence over the
   older surface-specific hooks, which remain available as compatibility fallbacks.
@@ -33526,14 +33941,20 @@ is no "every item in the tooltip" surface to hook a title or footer formatter on
   actually render *text*: after the global record sampler runs, it selects from those retained
   categories, always shows the first and last sampled label, and roughly evenly distributes the
   rest between them. A number is authoritative up to the number of sampled categories. `'auto'`
-  derives the cap after each resize from the resolved plot width and widest rendered caller label,
-  using the same deterministic 7px-per-
-  character estimate as label ellipsis plus 10px of lane breathing room. It therefore responds to
-  either `layout` mode without DOM text measurement or browser-specific font metrics. Unset (the
-  default) renders every label, unchanged. Each rendered category label is allocation-aware:
-  narrow/long text is ellipsized before paint, with the complete caller label retained as its
-  accessible name. Independently, the global 1,000-record safety sampler may bound both marks and
-  labels for very large category×series input.
+  re-selects after each resize from the resolved tick positions and the widest rendered caller
+  label, using the same deterministic 7px-per-character estimate as label ellipsis. Whenever the
+  first and last labels fit side by side, it keeps at least 10px of breathing room between every
+  adjacent pair of labels; when even those two do not fit, only they remain and label ellipsis
+  prevents overlap. Each label is measured where it paints: centered on its tick, except the first
+  and last category, which anchor toward the plot interior (mirrored under RTL) and so occupy their
+  whole width on the inner side of their tick. Label centers are spaced evenly between those two
+  boundary labels, so neither boundary pair is crowded. A `barX` that reorders the ticks away from
+  source order falls back to the width-only cap (plot width divided by the widest label plus 10px).
+  It therefore responds to either `layout` mode without DOM text measurement or browser-specific
+  font metrics. Unset (the default) renders every label, unchanged. Each rendered category label
+  is allocation-aware: narrow/long text is ellipsized before paint, with the complete caller label
+  retained as its accessible name. Independently, the global 1,000-record safety sampler may bound
+  both marks and labels for very large category×series input.
 - `barX?: (index: number) => number` (attribute: false, bar type only) — overrides the internal
   per-category x-origin formula (`plotX + i * slot`) used by both bars and their axis labels, so a
   consumer can pixel-align this chart's bars with a sibling `<lr-heatmap>` calendar's week columns
@@ -34050,7 +34471,7 @@ bounded-alternative sampling notice)
 `--lr-chart-tooltip-text` — same public host-level precedence, token names, and defaults as `lr-chart`
 (also `getComputedStyle`-resolved and CSS-color-validated on every draw; invalid expressions use
 concrete semantic fallbacks rather than retaining a prior canvas paint), but declared in its own stylesheet, not a
-re-export: `lr-box-plot` has no `zoom`, so no `reset-zoom-button` chrome exists here. A `BoxPlotSeries`
+re-export: `lr-box-plot` has no `zoom`, so no `reset-zoom-button` chrome exists here. A `LyraBoxPlotSeries`
 that sets no `color` is assigned an entry from the same `--lr-color-chart-1..8` ramp `lr-chart` uses,
 so `--lr-theme-color-chart-*` retheming reaches box plots too. That resolved color then layers two
 further per-series override tokens for the canvas paint, each wrapping modulo 8 like the underlying
@@ -34117,6 +34538,44 @@ loads are memoized per page.
 
 ---
 
+## Formatted labels in right-to-left layouts
+
+Every formatted chart label is bidi-isolated: it paints in the direction of its own first strong
+character, like `<bdi>` or a first-strong isolate, rather than in the chart's inherited direction.
+A number-first left-to-right string from `tickFormat`, `formatter`, `valueFormatter`,
+`tableCellFormatter`, `legendText` or an authored category label (`2.4 MiB/s`, `9:00 AM`, `-3`)
+therefore keeps its number-unit order inside `dir="rtl"`, and an Arabic- or Hebrew-script label
+keeps its own right-to-left order instead of being forced left-to-right. Axis placement, category
+order, boundary anchoring and label fitting are unchanged, and there is nothing to opt into — no
+text-direction hook is needed, and a formatter should return plain text without its own isolation
+controls.
+
+- `lr-lite-chart`: value-axis ticks, category ticks and axis titles (SVG `unicode-bidi: plaintext`);
+  the `legendText`/`formatter` legend value; the generated table's series headers, row headers and
+  cells; and, while visible, each value interpolated into a single-series data-list sentence (each
+  in its own `<bdi>`).
+- `lr-chart` (every typed subclass and `lr-histogram` included) and `lr-box-plot`: Chart.js tick
+  labels on every generated scale (radar/polar point labels included), axis titles, every tooltip
+  line, annotation labels and the `data-labels`/`stack-totals` labels are drawn inside a Unicode
+  directional embedding only where their first-strong direction differs from the canvas's (a
+  Chart.js `textDirection` set through `config` counts as the canvas's). A formatted value inside a
+  tooltip line (`Series: 2.4 MiB/s`) is also embedded on its own wherever it reads differently from
+  the line, so it keeps its order after an Arabic- or Hebrew-script series name. A left-to-right
+  chart with left-to-right labels therefore draws the formatter's strings exactly. A DOM legend
+  entry that shows a value isolates its label and value each in a `<bdi>`, and so do the generated
+  table's headers and cells.
+- Labels that a raw `config` passthrough draws on its own — scales, annotations or plugins it adds
+  beyond the generated ones — are drawn exactly as given; isolate those strings yourself if they
+  need it.
+- Isolation adds no bidi control characters to accessible names, live announcements, the visually
+  hidden data alternatives or CSV export. `lr-lite-chart`'s per-mark native SVG `<title>` hover
+  text stays the plain `pointText`/built-in string: the browser also exposes it as the mark's
+  accessible description, where control characters would reach speech and braille output.
+- The same rule covers `lr-gauge`'s value and label captions and `lr-heatmap`'s hover tooltip and
+  legend scale labels.
+
+---
+
 ## Chart streaming and export
 
 `lr-lite-chart` and `lr-chart` expose imperative helpers for live dashboards:
@@ -34724,7 +35183,11 @@ value, without suppressing the visible `name` heading.
   (`<lr-dialog>`'s close event was spelled `lr-dialog-close` before 10.0.0.) The name itself is not
   dialog-scoped in this library: nesting this viewer inside a consumer's own `<lr-dialog>` means
   that dialog's `lr-close` listener also observes this event — see `<lr-dialog>`'s own `lr-close`
-  section (in `overlays.md`) for the full list of emitters and the guard pattern.
+  section (in `overlays.md`) for the full list of emitters and the guard pattern. This `lr-close`
+  is not cancelable, and it is the viewer's only dismissal report: the shell dialog's own
+  `lr-show`, `lr-after-show`, `lr-initial-focus`, `lr-request-close`, `lr-hide`, and
+  `lr-after-hide` stay inside the viewer. A registered renderer's descendant dialog keeps those
+  events on their normal composed path.
 - `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
@@ -34761,11 +35224,15 @@ for the native download action's hover and pressed backgrounds.
 
 **Renderer registry exports:**
 
-- `DocumentFile` — the compatible mutable lookup input passed to `matches(file)` callbacks:
+- `DocumentFile` (deprecated, removal not before 23.0.0; use the structurally identical
+  `LyraDocumentFile`) — the compatible mutable lookup input passed to `matches(file)` callbacks:
   `{ name, mimeType, src, anchor?, highlights?, alt? }`. Adapter and legacy-render boundaries
   receive an immutable file snapshot whose highlights use the shared trimmed, nonempty,
-  first-wins identity projection.
-- `LyraDocumentFile` — the readonly file snapshot wrapped by every discriminated payload.
+  first-wins identity projection. Exported signatures, listed below, keep this name until its
+  removal; the two names are assignable to each other, so annotate your own code with
+  `LyraDocumentFile`.
+- `LyraDocumentFile` — the readonly file snapshot wrapped by every discriminated payload, and the
+  supported name for the file type.
 - `LyraDocumentRendererPayload` — readonly `kind: 'document' | 'av'` discriminated input wrapping an
   immutable `file`. The AV branch adds readonly `cues` and `tracks`; snapshots retain at most 10,000
   cues and 64 tracks, clone and freeze every retained record, and bound every retained string.
@@ -34775,7 +35242,8 @@ for the native download action's hover and pressed backgrounds.
 - `LyraDocumentRendererAdapterDefinition<K>` / `LyraDocumentRendererAdapter` — strongly typed
   authoring input and its factory-created, type-erased registry form. The callbacks adapt the legacy
   file to one payload kind, derive capabilities from that retained payload, and render it.
-- `DocumentRendererDefinition` (also `LyraDocumentRendererDefinition`) — a validated direct
+- `LyraDocumentRendererDefinition` (the deprecated `DocumentRendererDefinition` names the same
+  union until its removal, no earlier than 23.0.0) — a validated direct
   `{ render, matches?, capabilities? }`, adapted `{ adapter, matches? }`, or lazy
   `{ load, matches?, capabilities? }` definition; exactly one of `render`, `adapter`, and `load` is
   required. Static capabilities are rejected on adapted definitions so their adapter remains the
@@ -36588,9 +37056,13 @@ clipboard failure bubbles `lr-error` plus `lr-copy-error`
 ## `lr-geojson-viewer` / `lr-geojson-view`
 
 Document-registry bridge that fetches, validates, and renders a GeoJSON file through `<lr-map>`'s
-`dataLayers`. The canonical class is `LyraGeoJsonViewer`; the pre-v9 `lr-geojson-view` tag and
-`LyraGeojsonView` class name remain compatibility aliases. The document registry renders the
-canonical tag and matches `application/geo+json` and `.geojson` filenames.
+`dataLayers`. The canonical class is `LyraGeoJsonViewer`. The pre-v9 `lr-geojson-view` tag, its
+`LyraGeojsonView` class and `LyraGeojsonViewEventMap` type are deprecated compatibility aliases
+(removal not before 23.0.0; this replaces the earlier promise to keep them permanently): they keep
+working unchanged until then, and connecting `lr-geojson-view` logs a one-time development warning.
+Rename them to `lr-geojson-viewer`, `LyraGeoJsonViewer` and `LyraGeoJsonViewerEventMap`. The
+document registry renders the canonical tag and matches `application/geo+json` and `.geojson`
+filenames.
 
 Validates the parsed JSON is a `Feature`/`FeatureCollection`/bare geometry (one of `Point`,
 `LineString`, `Polygon`, `MultiPoint`, `MultiLineString`, `MultiPolygon`, `GeometryCollection`) before
@@ -36661,8 +37133,12 @@ but working state, since the `lr-json-viewer` fallback below it still renders th
 size of `[part="base"]`, matching every other viewer in this family. It is also settable via the
 `maxHeight` property, which writes this token inline on `[part="base"]`.
 
-The canonical tag is registered by importing `geojson-viewer/geojson-viewer.js`; the permanent
-compatibility tag and old deep route remain available through `geojson-view/geojson-view.js`.
+The canonical tag is registered by importing `components/lr-geojson-viewer.js` (deep route
+`components/viewers/geojson-view/geojson-viewer.js`). The deprecated `components/lr-geojson-view.js`,
+`components/viewers/geojson-view/geojson-view.js` and `geojson-view.class.js` routes register or
+export the alias (the registration routes also register `lr-geojson-viewer`) and keep working until
+their removal, no earlier than 23.0.0; an application importing one of them only to register the
+canonical tag switches to `components/lr-geojson-viewer.js`.
 Remote
 resources are capped at 25 MB; exceeding it surfaces the localized `documentPreviewResourceTooLarge`
 message instead of the map. Lyra supports MapLibre v5 and v6; consumers must import its CSS.
@@ -37344,7 +37820,9 @@ uses for its own `[part="body"]`.
   indented. It copies source text without the renderer's terminal newline, preserving leading tabs
   whenever they match the displayed code after expansion. Custom code renderers and pre-escaped
   code bypass it. `codeBlockChrome: boolean = false` (attribute `code-block-chrome`) is a
-  compatibility spelling; either property enables the header. Plain streaming defers headers until
+  deprecated compatibility spelling (removal not before 23.0.0; setting it logs a one-time
+  development warning): either property enables the header, so use `code-block-header`. Plain
+  streaming defers headers until
   settle; progressive streaming adds them to committed blocks. The button has a localized accessible
   name and native pointer title, with no custom tooltip on keyboard focus. In sanitize mode enabling
   the header also removes authored style elements and their CSS text to prevent visual copy
@@ -37635,8 +38113,9 @@ instance's isolated peer-neutral configurable parser; `htmlMode: 'sanitize' | 'e
 `link-target`), `internalLinkPrefix: string = ''` (attribute `internal-link-prefix`),
 `headingOffset: number = 0` (attribute `heading-offset`), `streaming: boolean = false` (reflected),
 `streamingRender: MarkdownStreamingRender = 'plain'` (attribute `streaming-render`, not reflected),
-`codeBlockHeader: boolean = false` (attribute `code-block-header`) with its compatibility alias
-`codeBlockChrome: boolean = false` (attribute `code-block-chrome`),
+`codeBlockHeader: boolean = false` (attribute `code-block-header`) with its deprecated
+compatibility alias `codeBlockChrome: boolean = false` (attribute `code-block-chrome`; removal not
+before 23.0.0),
 `highlightCode: boolean = true` (attribute
 `highlight-code`), `languages: Record<string, ShikiLanguageSource> = {}` (attribute: false) —
 required, unlike `<lr-markdown>`'s optional `languages?:`; empty (the default) means every fenced
@@ -37726,7 +38205,7 @@ The Markdown part set also includes `task-list`, `task-item`, `task-item-checked
 `task-checkbox`, `table-wrapper`, `code-block-frame`, `code-block-copy-success`,
 `code-block-copy-error` and `streaming-tail`. `codeBlockHeader: boolean = false`
 (attribute `code-block-header`) enables the code-block header; `codeBlockChrome` (attribute
-`code-block-chrome`) is its compatibility alias. Successful and
+`code-block-chrome`) is its deprecated compatibility alias (removal not before 23.0.0). Successful and
 failed writes pass through as `lr-copy` and `lr-copy-error`, carrying the immutable clipboard
 outcome, bubbling and composed.
 
@@ -38408,10 +38887,28 @@ plus bubbling/composed `blur` and `focus` with `null` detail relayed from the re
 
 `start`/`content`/`excerpt`/`meta` must all stay non-focusable — see the `role="button"` note below.
 
-**CSS parts:** `base`, `active-indicator` (decorative, rendered only while `active`),
+**CSS parts:** `base`, `base-menu-open` (state alias on `base` while a menu opened from the
+`actions` slot is open), `active-indicator` (decorative, rendered only while `active`),
 `select-button`, `start`, `content`, `label`, `label-input`, `rename-button`, `excerpt`, `meta`, `timestamp`,
 `actions`
 
+**Custom state:** `menu-open` — the host matches `:state(menu-open)` while an `lr-dropdown`,
+`lr-popover` or `lr-context-menu` opened from the `actions` slot is open (including one composed
+inside another component's shadow root), however it was opened; `[part="base"]` then also carries
+`base-menu-open`, and the row keeps its hover tint (an `active` row keeps its active tint). The menu
+sits in the browser top layer, where Chromium and WebKit stop matching `:hover` and `:focus-within`
+on the row while the pointer or focus is inside it, so a hover- or focus-revealed actions trigger
+must key on this state as well:
+
+```css
+lr-conversation-item .row-menu {
+  opacity: 0;
+}
+lr-conversation-item:is(:hover, :focus-within, :state(menu-open)) .row-menu {
+  opacity: 1;
+}
+```
+
 **Themeable custom properties:** `--lr-conversation-item-active-bg` (default
 `var(--lr-color-brand-quiet)`) — the row's background while `active`. `--lr-conversation-item-active-color`
 (default `var(--lr-color-text)`) — the text color of `[part='excerpt']` and `[part='timestamp']`
@@ -38846,9 +39343,11 @@ properties existed:
 - `headingOffset: number = 0` (attribute `heading-offset`) — forwarded to the composed
   `<lr-markdown>`'s own `headingOffset`.
 - `streamingRender: MarkdownStreamingRender = 'plain'` (attribute `streaming-render`, not reflected)
-  and `codeBlockHeader: boolean = false` (attribute `code-block-header`), with its compatibility
-  alias `codeBlockChrome: boolean = false` (attribute `code-block-chrome`) — forwarded to the
-  composed Markdown element. Their settled-block streaming behavior, code-copy behavior, and defaults match
+  and `codeBlockHeader: boolean = false` (attribute `code-block-header`), with its deprecated
+  compatibility alias `codeBlockChrome: boolean = false` (attribute `code-block-chrome`; removal not
+  before 23.0.0; setting it logs a one-time development warning) — forwarded to the composed
+  Markdown element, which receives either header option as its own `codeBlockHeader`. Their
+  settled-block streaming behavior, code-copy behavior, and defaults match
   `<lr-markdown>`; see its **Properties** section above.
   Use `streaming-render="progressive"` with `content-mode="markdown"`: in `auto` mode the element
   switches from plain text to Markdown when detection first succeeds, which replaces the displayed
@@ -38944,7 +39443,8 @@ showing the previous stream's stale final content for the length of the window.
 
 Rendering itself is never reimplemented here: Markdown mode composes `<lr-markdown>` directly,
 forwarding this component's own `streaming` through as that component's `streaming` hint prop,
-  `streamingRender`, `codeBlockHeader`, `codeBlockChrome`, `languages` verbatim, and the rest of `<lr-markdown>`'s
+  `streamingRender`, `codeBlockHeader` (on when either this element's `codeBlockHeader` or its
+  deprecated `codeBlockChrome` is), `languages` verbatim, and the rest of `<lr-markdown>`'s
   configuration surface verbatim too (`tabSize`, `htmlMode`, `gfm`, `linkTarget`,
   `internalLinkPrefix`, `headingOffset`, `highlightCode`, `headingAnchors`, `math`, `maxHeight` —
   see **Properties** above); plain-text mode
@@ -38975,7 +39475,7 @@ The Markdown part set also includes `task-list`, `task-item`, `task-item-checked
 `task-checkbox`, `table-wrapper`, `code-block-frame`, `code-block-copy-success`,
 `code-block-copy-error` and `streaming-tail`. `codeBlockHeader: boolean = false`
 (attribute `code-block-header`) enables the code-block header; `codeBlockChrome` (attribute
-`code-block-chrome`) is its compatibility alias. Successful and
+`code-block-chrome`) is its deprecated compatibility alias (removal not before 23.0.0). Successful and
 failed writes pass through as `lr-copy` and `lr-copy-error`, carrying the immutable clipboard
 outcome, bubbling and composed.
 
@@ -39013,12 +39513,14 @@ attribute names, and defaults described under `<lr-streaming-text>`'s own **Prop
 `rel="noopener noreferrer"` whenever a `target` is emitted); `internalLinkPrefix: string = ''`
 (attribute `internal-link-prefix`); `headingOffset: number = 0` (attribute `heading-offset`);
 `streamingRender: MarkdownStreamingRender = 'plain'` (attribute `streaming-render`, not reflected);
-`codeBlockHeader: boolean = false` (attribute `code-block-header`) and its compatibility alias
-`codeBlockChrome: boolean = false` (attribute `code-block-chrome`); `highlightCode: boolean = true`
+`codeBlockHeader: boolean = false` (attribute `code-block-header`) and its deprecated
+compatibility alias `codeBlockChrome: boolean = false` (attribute `code-block-chrome`; removal not
+before 23.0.0); `highlightCode: boolean = true`
 (attribute `highlight-code`); `headingAnchors: boolean = false` (attribute `heading-anchors`);
 `math: boolean = false`; `maxHeight: string = ''` (attribute `max-height`). All are forwarded to
 the composed `<lr-markdown-core>`, with matching behavior and defaults. `streamingRender` controls
-progressive output, and `codeBlockHeader` (or its `codeBlockChrome` alias) enables the localized
+progressive output, and `codeBlockHeader` (or its deprecated `codeBlockChrome` alias, which reaches
+the composed element as `codeBlockHeader`) enables the localized
 code label and source-copy action.
 
 **Exported helper:** `looksLikeMarkdown(text: string): boolean` — the same standalone heuristic
@@ -39069,7 +39571,7 @@ The Markdown part set also includes `task-list`, `task-item`, `task-item-checked
 `task-checkbox`, `table-wrapper`, `code-block-frame`, `code-block-copy-success`,
 `code-block-copy-error` and `streaming-tail`. `codeBlockHeader: boolean = false`
 (attribute `code-block-header`) enables the code-block header; `codeBlockChrome` (attribute
-`code-block-chrome`) is its compatibility alias. Successful and
+`code-block-chrome`) is its deprecated compatibility alias (removal not before 23.0.0). Successful and
 failed writes pass through as `lr-copy` and `lr-copy-error`, carrying the immutable clipboard
 outcome, bubbling and composed.
 
@@ -39781,7 +40283,10 @@ MessageFeedbackValue = null` (attribute `feedback-rating`) — forwarded to the
 opens). `feedbackPending: boolean` (read-only, nonreflecting) — true only while the current built-in
 feedback control awaits settlement; it has no `feedback-pending` attribute or change event.
 `revealOnInteraction: boolean = false` (reflected, attribute `reveal-on-interaction`) — hides
-the bar until the closest `lr-chat-message` ancestor is hovered, or the toolbar contains focus.
+the bar until the closest `lr-chat-message` ancestor is hovered, or the toolbar contains focus. It
+also stays revealed while an `lr-dropdown`, `lr-popover` or `lr-context-menu` opened from a slotted
+control is open, since that menu sits in the browser top layer, where focus inside it does not
+count as focus within the toolbar in Chromium and WebKit.
 `label?: string` — accessible name override for the toolbar. Omitting it localizes the default
 `messageActionsLabel` message; an explicit empty string suppresses that default and renders no
 label. `accessibleLabel: string | null =
@@ -40338,8 +40843,11 @@ ancestor `--lr-positioning-strategy` still wins), and a trapped `fixed` menu ope
 outside the list, in the browser top layer where the native Popover API exists, in left-to-right
 and right-to-left documents, with no consumer CSS. A promoted menu whose trigger scrolls out of the
 list is hidden until the trigger returns. Where the Popover API is absent, the row holding an open
-`lr-dropdown` stops transforming while it is open, so its menu is still not clipped. Unset renders
-only the built-in
+`lr-dropdown` stops transforming while it is open, so its menu is still not clipped. While such a
+menu is open its row carries `row-item-base-menu-open` (see the parts below) and keeps its built-in
+hover tint. Arrow, Home and End keys a returned control already handled (`lr-menu` moving between
+its own items, a dropdown trigger opening its menu) stay with that control rather than also moving
+focus to another row. Unset renders only the built-in
 `rowActions`.
 `renderStart?: (thread: LyraChatThread) => TemplateResult` (attribute: false) — renders non-interactive
 start-side content in each virtualized row. `renderExcerpt?: (thread: LyraChatThread) => TemplateResult`
@@ -40422,10 +40930,30 @@ reach callback-rendered descendants through these parts). `row-excerpt` wraps `r
 output, which is slotted into the row item's own `excerpt` slot.
 
 Data mode additionally forwards each row `<lr-conversation-item>`'s own parts under a `row-item-`
-prefix: `row-item-base`, `row-item-active-indicator`, `row-item-select-button`, `row-item-start`, `row-item-content`,
+prefix: `row-item-base`, `row-item-base-menu-open`, `row-item-active-indicator`, `row-item-select-button`, `row-item-start`, `row-item-content`,
 `row-item-label`, `row-item-label-input`, `row-item-rename-button`, `row-item-excerpt`,
 `row-item-meta`, `row-item-timestamp`, `row-item-actions`.
 
+**Row menu-open state:** `row-item-base-menu-open` is carried by `row-item-base` while a menu that
+`renderActions` opened from that row (`lr-dropdown`, `lr-popover` or `lr-context-menu`) is open,
+however it was opened. That menu sits in the browser top layer, where Chromium and WebKit stop
+matching `:hover` and `:focus-within` on the row while the pointer or keyboard focus is inside it.
+A menu trigger revealed on row hover or focus must key on this state too, or it hides while its own
+menu is open — and a `display`-based reveal hides the menu with it, because an open menu is
+concealed once its trigger stops being measurable. `::part()` cannot be followed by a descendant,
+so carry the reveal to `row-actions` through an inherited custom property:
+
+```css
+lr-thread-list::part(row-item-base):hover,
+lr-thread-list::part(row-item-base):focus-within,
+lr-thread-list::part(row-item-base-menu-open) {
+  --app-row-actions-opacity: 1;
+}
+lr-thread-list::part(row-actions) {
+  opacity: var(--app-row-actions-opacity, 0);
+}
+```
+
 **Themeable excerpt highlights:** `<mark>` descendants returned by `renderExcerpt` use
 `--lr-thread-list-excerpt-highlight-background` (default `var(--lr-color-warning-quiet)`),
 `--lr-thread-list-excerpt-highlight-foreground` (default `inherit`),
@@ -41199,7 +41727,9 @@ and `codeBlockHeader: boolean = false` (attribute `code-block-header`) — forwa
 and reasoning Markdown parts while `contentMode="markdown"`. Progressive mode renders settled
 blocks during a streaming part and preserves the `plain` fallback by default; the header adds the
 source language label and localized copy action to built-in code blocks.
-`codeBlockChrome: boolean = false` (attribute `code-block-chrome`) is an equivalent enabling alias. These settings do not replace
+`codeBlockChrome: boolean = false` (attribute `code-block-chrome`) is a deprecated equivalent
+enabling alias (removal not before 23.0.0; setting it logs a one-time development warning), and the
+parts' Markdown elements receive either option as `codeBlockHeader`. These settings do not replace
 the `MessagePart.state` lifecycle or affect `contentMode="plain"`.
 `maxRenderedParts: number = 0` (attribute `max-rendered-parts`) — `0` (the default) renders every
 part, unbounded, matching every prior release; a positive value windows rendering to the newest N
@@ -41237,17 +41767,24 @@ duration; expanding shows arguments, error and result in place) and pairs it wit
 - Everything else renders as in chip display: unpaired results, a result whose call is outside the
   rendered window, duplicate results after the first, and custom-rendered calls or results. A
   second call part with the same invocation id renders its own unpaired block.
-- The block binds `name`, `callId` and `args` from the invocation, and `redactedFields` from the
+- The block binds `name`, `displayName`, `callId` and `args` from the invocation, and `redactedFields` from the
   invocation-level paths described under redaction below; `result` from
   the paired part (else `invocation.result`); `error` from the paired part when it carries one (else
   `invocation.error`); and `durationMs = endedAt - startedAt` when both are set (else no duration).
   `expanded` is never bound, so a user-expanded block stays open across `parts` updates.
-- Block status, first match wins: invocation `denied` → `denied`; invocation `error` or a paired
-  error result → `error`; a paired result still `streaming` → `running`; any paired result →
+- Block status, first match wins: invocation `denied` → `denied`; invocation `incomplete` (a call
+  that ended without a result, 21.1.0) → `incomplete`, whatever result part is paired; invocation
+  `error` or a paired error result → `error`; a paired result still `streaming` → `running`; any paired result →
   `success`; otherwise the invocation's own status (an unknown value → `pending`), so a call still
   waiting on its result keeps showing `pending`/`running`.
 - The tool-call wrapper stretches to the message width in block display.
 
+**Display name in both displays** (21.1.0). An invocation's `displayName` (the application's own,
+already-translated tool label) is bound to the chip's or the block's `displayName`, so the visible
+and announced tool name is the translated one while `name` still selects the result renderer and
+is still what `lr-tool-call-chip-select` and `lr-render-error` report. A non-string value is not
+forwarded.
+
 **Redaction in both displays.** An invocation's `redactedFields` (dotted paths rooted at
 `args`/`result`/`error`, see `<lr-tool-call-block>`) masks every built-in rendering of its payload
 with the localized `Value hidden`: in block display the block's details; in chip display, and for
@@ -41407,7 +41944,11 @@ textarea, paired with `lr-input` and `lr-change`; `lr-submit` (`{ value }`),
 `lr-audio-request`, `lr-attachment-retry` (`{ attachmentId }`), and cancelable
 `lr-attachment-preview-request` (`{ attachmentId, name, mimeType, src }`). Child events are stopped
 and re-emitted from `lr-prompt-input`; all composed interactions are suppressed while `disabled`,
-including a child event dispatched in the same turn that disables the host.
+including a child event dispatched in the same turn that disables the host. The one deliberate
+exception is the built-in voice picker's preview pair: its cancelable `lr-preview-request`
+(`{ voiceId, previewUrl? }`) and `lr-preview-change` (`{ voiceId }`) reach the host unchanged, so a
+host can play its own TTS preview (call `preventDefault()`) for catalog entries without a
+`previewUrl`, including plain-string catalogs.
 
 **Slots:** `controls`; `start` (attachment-control content before the textarea); `chips`; `end`
 (custom send/stop action); and `footer`. `start` replaces the default attachment trigger and `end`
@@ -41523,8 +42064,10 @@ movement starts from the action that received the event rather than stale contro
 private so controlled rect updates cannot be silently overridden by stale authored CSS.
 **Themeable custom properties:** `--lr-selection-toolbar-placement-gap` (default
 `var(--lr-space-s)`) is the non-negative distance from the selection and from viewport edges while
-the toolbar avoids collisions. It accepts unitless pixel values and `px`, `rem`, and `em` values; unsupported
-values fall back to the default and negative values clamp to `0`. Collision math uses the active
+the toolbar avoids collisions. It accepts unitless pixel values, `px`, `rem`, and `em` values, and
+CSS length math (`calc()`, `min()`, `max()`, `clamp()`) resolved in its live theme scope. Percentages
+have no placement-gap basis. Invalid values fall back to the default and negative values clamp to
+`0`. Collision math uses the active
 `visualViewport` bounds and offsets when available, including after visual-viewport changes.
 
 The toolbar is a floating surface and paints from the **shared overlay-surface family** (16.0.0):
@@ -42073,11 +42616,17 @@ its content.
 **Properties:**
 
 - `name: string = ''` — the tool/function name, e.g. `web_search`
+- `displayName?: string` (attribute `display-name`, 21.1.0) — the application's own,
+  already-translated label for the tool (e.g. `Lecture d’un fichier`). It replaces `name` in the
+  visible `name` part and the chip's accessible name only; `lr-tool-call-chip-select` still reports
+  the raw `name`. Unset or empty shows `name`
 - `category: string = ''` — optional grouping label, e.g. `research`
-- `status: 'pending'|'running'|'success'|'error'|'denied' = 'pending'` (reflected) — drives the
-  glyph, accent color, and `status-text`; same status vocabulary as `<lr-tool-result-dialog>` so a
-  call's chip and its detail dialog always agree; unknown runtime values render the pending icon,
-  text, and accessible label instead of failing the update
+- `status: 'pending'|'running'|'success'|'error'|'denied'|'incomplete' = 'pending'` (reflected) —
+  drives the glyph, accent color, and `status-text`; same status vocabulary as
+  `<lr-tool-result-dialog>` so a call's chip and its detail dialog always agree; `incomplete`
+  (21.1.0) is a call that ended without a result (an interrupted stream, a cancelled run) and reads
+  `Incomplete` (`statusIncomplete`) with its own static glyph in the neutral `pending` tone; unknown
+  runtime values render the pending icon, text, and accessible label instead of failing the update
 - `summary: string = ''` — short human-readable status text, e.g. `Searching web…`
 - `durationMs?: number` (attribute `duration-ms`) — how long the call took, in milliseconds; the
   `duration` part is omitted entirely when unset
@@ -42102,7 +42651,7 @@ content — assigned content wins; otherwise the `icon` prop is rendered as a li
 the built-in glyph for the current `status` is used)
 
 **CSS parts:** `base` (the clickable `<button>`), `icon`, `label` (wrapper around `category`, `name`,
-`summary`), `category`, `name`, `summary`, `meta` (wrapper around `status-text` and `duration`),
+`summary`), `category`, `name` (the tool name, or `display-name` when set), `summary`, `meta` (wrapper around `status-text` and `duration`),
 `status-text`, `duration`, `tooltip` (the floating detail popup, only meaningful while open)
 
 **Themeable custom properties:** `--lr-tool-call-chip-spin` (default `var(--lr-transition-ambient)`,
@@ -42110,7 +42659,7 @@ i.e. `1.8s ease-in-out` at the shipped token value and `0.001ms linear` under
 `prefers-reduced-motion` — running-icon animation duration/timing) and `--lr-transition-ambient`
 (default `1.8s ease-in-out` — pending-icon pulse duration/timing).
 `--lr-tool-call-chip-accent`, `--lr-tool-call-chip-bg`, and `--lr-tool-call-chip-border` are public
-component hooks whose private defaults follow `status` (e.g. `pending` →
+component hooks whose private defaults follow `status` (e.g. `pending` and `incomplete` →
 `--lr-color-text-quiet`/`--lr-color-surface`/`--lr-color-border`; `running` → brand; `success` →
 success; `error` → danger; `denied` → warning). Set them on an ancestor to retheme a subtree or
 directly on one chip; either public value remains authoritative in every status. Shared tokens
@@ -42217,7 +42766,7 @@ Direction: a text fallback (`::part(fallback-text)`) uses `unicode-bidi: plainte
 - `copyable: boolean = false` (reflected) — shows a copy-to-clipboard affordance alongside the
   fallback view, for either `fallback` kind: forwarded to `<lr-json-viewer>`'s own `copyable` for
   `"json"`, or a `<lr-copy-button>` rendered next to the text for `"text"`.
-- `status: 'pending'|'running'|'success'|'error'|'denied' = 'success'` (reflected) — the outcome of
+- `status: 'pending'|'running'|'success'|'error'|'denied'|'incomplete' = 'success'` (reflected) — the outcome of
   the currently-rendered result, as reported by the matched renderer's own `context.reportStatus()`
   (see below). Reset to `'success'` immediately before every `render()` call, so a renderer that
   never calls `reportStatus` — including every pre-existing 2-arg renderer written before this
@@ -42299,8 +42848,9 @@ DirectToolRendererDefinition }>` and `render?: never` — lazy loader
 **`ToolRenderContext`** — the shape of `render()`'s 3rd argument:
 
 - `reportStatus: (status: ToolResultStatus) => void` — reports this render's outcome without
-  throwing. `ToolResultStatus` is `'pending' | 'running' | 'success' | 'error' | 'denied'`, the same
-  union `<lr-tool-result-dialog>`/`<lr-tool-call-chip>` use, re-exported from this module. Calling
+  throwing. `ToolResultStatus` is `'pending' | 'running' | 'success' | 'error' | 'denied' |
+  'incomplete'`, the same union `<lr-tool-result-dialog>`/`<lr-tool-call-chip>` use, re-exported
+  from this module. Calling
   it is entirely optional: a renderer that never calls it leaves `<lr-tool-result-view>`'s `status`
   property at its default, `'success'`. This threads through the lazy `load()` path exactly the
   same way — a `render()` resolved via `load()` receives the same 3rd `context` argument as one
@@ -42432,8 +42982,10 @@ title.
   cloning that name. A direct property assignment made without the attribute can name the panel
 - `toolName: string = ''` (attribute `tool-name`) — the tool's name, rendered prominently in the
   header
-- `status: 'pending'|'running'|'success'|'error'|'denied' = 'pending'` (reflected) — drives the
-  header's status badge; same status vocabulary as `<lr-tool-call-chip>`
+- `status: 'pending'|'running'|'success'|'error'|'denied'|'incomplete' = 'pending'` (reflected) —
+  drives the header's status badge; same status vocabulary as `<lr-tool-call-chip>`. `incomplete`
+  (21.1.0) is a call that ended without a result; its badge reads `Incomplete` in the neutral
+  pending look, through its own `--lr-tool-result-dialog-incomplete-*` pair
 - `durationMs?: number` (attribute `duration-ms`) — how long the call took, in milliseconds; omitted
   from the header entirely when unset
 - `maximized: boolean = false` (reflected) — near-fullscreen presentation of the same open dialog
@@ -42536,6 +43088,8 @@ Backdrop clicks leave the dialog open by default; add `light-dismiss` to opt in,
 - `--lr-tool-result-dialog-error-bg` — Error status background. Default: `var(--lr-color-danger-quiet)`.
 - `--lr-tool-result-dialog-denied-color` — Denied status foreground. Default: `var(--lr-color-warning)`.
 - `--lr-tool-result-dialog-denied-bg` — Denied status background. Default: `var(--lr-color-warning-quiet)`.
+- `--lr-tool-result-dialog-incomplete-color` — Incomplete status foreground (21.1.0). Default: `var(--lr-color-text-quiet)`.
+- `--lr-tool-result-dialog-incomplete-bg` — Incomplete status background (21.1.0). Default: `transparent`.
 
 ---
 
@@ -43294,8 +43848,9 @@ fired once up front at connect time and after every effective change; serializat
 publish their root message as `errors.base` and `formError`), and no-detail `focus`/`blur` events for
 generated native text/number inputs. The composed
 `<lr-select>` controls already bubble their own focus/blur bridges through the host.
-Nested control events (`input`, `change`, `lr-change`, select show/hide, and option mutation) are
-contained at the form boundary; consumers receive the single form-level `lr-input` contract.
+Nested control events (`input`, `change`, `lr-change`, the selects' `lr-show`/`lr-after-show`/
+`lr-hide`/`lr-after-hide`, and option mutation) are contained at the form boundary; consumers receive
+the single form-level `lr-input` contract.
 `lr-invalid` (no detail) is the bubbling/composed, cancelable alias emitted when the complete
 parameter form fails a native validity check; preventing it also prevents the native `invalid`
 event's default validation UI.
@@ -44969,9 +45524,9 @@ primitives, with retry counts and sensitive-field redaction.
 **Properties:**
 
 - `entries: readonly ToolTimelineEntry[] = []` (attribute: false) — `ToolTimelineEntry` **extends
-  `ToolInvocation` from `@aceshooting/lyra-ui/ai`** (`{ id: string; name: string; args:
-Record<string, unknown>; status: ToolCallStatus; result?: unknown; error?: string }`, where
-  `ToolCallStatus = 'pending' | 'running' | 'success' | 'error' | 'denied'`) with `{ startedAt?:
+  `ToolInvocation` from `@aceshooting/lyra-ui/ai`** (`{ id: string; name: string; displayName?:
+string; args: Record<string, unknown>; status: ToolCallStatus; result?: unknown; error?: string }`, where
+  `ToolCallStatus = 'pending' | 'running' | 'success' | 'error' | 'denied' | 'incomplete'`) with `{ startedAt?:
 number; endedAt?: number; retryCount?: number; redactedFields?: readonly string[]; needsApproval?: boolean;
 approved?: boolean; sourceKey?: string; icon?: string }`. `sourceKey` identifies the owning run or
   source generation when invocation ids can be reused; every expansion, activation, renderer error,
@@ -44979,7 +45534,12 @@ approved?: boolean; sourceKey?: string; icon?: string }`. `sourceKey` identifies
   are omitted; a blank optional `sourceKey` is treated as absent. Duplicate occurrences of the same
   pair are normalized before any lookup with a deterministic first-occurrence-wins policy. `icon` is a
   literal hint forwarded to the composed tool-call chip. A foreign runtime `status` normalizes once
-  to `pending` before both the timeline row and its composed chip render.
+  to `pending` before both the timeline row and its composed chip render. `displayName` (21.1.0),
+  the application's own translated tool label, is forwarded to the chip's `displayName` and names
+  the entry's details disclosure (`Details for Lecture d’un fichier`); an empty, omitted or
+  non-string value shows `name`. `name` still selects the result renderer, is still the `toolName`
+  in `lr-tool-render-error`, and still names the tool in the approval dialog, so the reviewer
+  authorizes the exact tool.
   Timestamps are epoch milliseconds; entries sort ascending by `startedAt`,
   and an entry with none sorts after every timed entry (keeping its relative position among other
   untimed ones) and renders no visible timestamp. `startedAt`+`endedAt` derive the `durationMs`
@@ -45060,6 +45620,8 @@ per-entry timeline marker dot's size, which also sets the entry grid's leading c
 `status="denied"` entry, decoupled from the pending-approval border color below so either can be
 retinted independently; `--lr-tool-timeline-pending-marker-color` (default
 `var(--lr-color-text-quiet)`) — rail-dot color for a `status="pending"` entry;
+`--lr-tool-timeline-incomplete-marker-color` (21.1.0, default `var(--lr-color-text-quiet)`) —
+rail-dot color for a `status="incomplete"` entry, independent of the pending one;
 `--lr-tool-timeline-pending-approval-border-color` (default
 `var(--lr-color-warning)`) — color of the entry body's leading border while that entry's
 `data-pending-approval` is `"true"`.
@@ -45970,6 +46532,7 @@ These named interfaces and helper signatures are available to typed integrations
     // Inherited from ToolInvocation.
     id: string;
     name: string;
+    displayName?: string;
     args: Record<string, unknown>;
     status: ToolCallStatus;
     result?: unknown;
@@ -46030,11 +46593,19 @@ progress, and `No data` only for a terminal status.
 **Properties:**
 
 - `name: string = ''` — tool name; an empty name renders the localized generic `Tool call` label
+- `displayName?: string` (attribute `display-name`, 21.1.0) — the application's own,
+  already-translated label for the tool. It replaces `name` inside the localized header verb only
+  (`Used Lecture d’un fichier`), so the status wording stays localized; `name` still selects the
+  result renderer and is still reported in `lr-render-error`. Unset or empty shows `name`; a
+  `label` override replaces the whole header, this included
 - `callId: string = ''` (attribute `call-id`) — invocation id echoed in `lr-toggle` and
   `lr-render-error` details
 - `status: ToolCallStatus = 'pending'` (reflected, including the default) —
-  `'pending'|'running'|'success'|'error'|'denied'`; selects the header verb, glyph and accent.
-  Values outside the set normalize and reflect as `pending`
+  `'pending'|'running'|'success'|'error'|'denied'|'incomplete'`; selects the header verb, glyph
+  and accent. `incomplete` (21.1.0) is a call that ended without a result (an interrupted stream, a
+  cancelled run): it reads `Did not finish using {name}` (`toolCallBlockHeaderIncomplete`), or
+  `Incomplete` (`statusIncomplete`) in `status-text` beside a `label`, with a static glyph and the
+  neutral accent. Values outside the set normalize and reflect as `pending`
 - `expanded: boolean = false` (reflected) — whether the details are shown
 - `label?: string` — header override, used verbatim (including `''`); when set, the localized
   status text renders beside it in `status-text`. Unset renders the localized status verb
@@ -46085,7 +46656,8 @@ set), `duration` (only while finite), `body` (the disclosed region), `args`, `ar
   header/body divider
 - `--lr-tool-call-block-radius` (default `var(--lr-radius)`) — card radius
 - `--lr-tool-call-block-accent` — status glyph colour; its private default follows `status`
-  (`--lr-color-text-quiet`, then brand while running, success, danger on error, warning when denied)
+  (`--lr-color-text-quiet` while pending or incomplete, then brand while running, success, danger
+  on error, warning when denied)
 - `--lr-tool-call-block-error-color` (default `var(--lr-color-danger)`) — error section text
 
 The running glyph spins and the pending glyph pulses at `--lr-transition-ambient`; both stop under
@@ -47161,7 +47733,9 @@ string; mimeType?: string; name?: string; children?: LyraSourceEntry[] }`; flat
 **Events:** `lr-sources-change` (`detail: { selectedSourceIds }`, the complete updated leaf-id array,
 fired after every toggle including select-all. Also fired when a `sources` reassignment prunes a
 previously-selected id that is no longer a valid leaf. Not fired when a consumer sets
-`selectedSourceIds` directly; that assignment is normalized silently).
+`selectedSourceIds` directly; that assignment is normalized silently). The select-all checkbox's
+own `lr-checkbox-toggle-request`, native `input`/`change`, and `lr-input`/`lr-change` stay inside
+the component; `lr-sources-change` is the host-level report of that toggle.
 
 **Slots:** none.
 
@@ -48336,7 +48910,9 @@ region. Initial empty content, loading intermediates, and reconnects are not rep
 - `lr-select` (`detail: RetrievalResultsSelectDetail` = `{ chunkIds: string[]; chunks: RetrievalChunk[] }`)
   — the _complete_ updated selection, both as ids and as exactly one canonical record per id, so a
   host needn't re-look-up ids against its own copy on every toggle. This derived detail is always
-  canonicalized nonblank/first-wins regardless of the legacy `dedupe` switch.
+  canonicalized nonblank/first-wins regardless of the legacy `dedupe` switch. It is the only
+  host-level report of a row toggle: the row checkbox's `lr-checkbox-toggle-request`, native
+  `input`/`change`, and `lr-input`/`lr-change` stay inside the component.
 - `lr-load-more` (`detail: null`) — from the virtual list's scroll-near-bottom detection while
   virtualized, or the `[part="load-more"]` button otherwise. Only fires while `hasMore` is true and
   `loading` is false.